> ## Documentation Index
> Fetch the complete documentation index at: https://cli-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration & permissions

> Configure RELAI permission profiles, path rules, credentials, and runtime-secret boundaries.

Choose an approval profile, restrict project paths, and keep authentication and runtime secrets in the right local files.

## Inspect the boundary before a workflow

<Tabs>
  <Tab title="Ask your coding agent">
    <Prompt description="Explain the effective RELAI permission profile and path restrictions for this repository without changing anything. Do not reveal credential or environment values. Tell me which reads, writes, and commands would pause for approval." actions={["copy"]}>
      Explain the effective RELAI permission profile and path restrictions for this repository without changing anything. Do not reveal credential or environment values. Tell me which reads, writes, and commands would pause for approval.
    </Prompt>
  </Tab>

  <Tab title="Run in terminal">
    After reviewing the boundary, initialize with your chosen profile. This command
    creates and validates project files; it is not a read-only inspection.

    ```sh theme={"system"}
    relai init --permissions ask
    ```
  </Tab>
</Tabs>

## Choose an approval profile

`relai setup` records `auto` when no global profile exists. On commands that expose it, `--permissions` overrides the global profile for that invocation. Simulation and
optimization do not expose this flag; check nested `--help`.

| Profile | Behavior | Use it when |
| - | - | - |
| `auto` | Otherwise-permitted reads, writes, and commands proceed automatically. Path denials and protected files still apply. | You trust the configured project boundary and want the least interruption. |
| `accept_edits` | Otherwise-permitted reads and writes proceed; project or dependency code execution pauses for approval. | You accept file edits but want to review probes, installs, builds, tests, scripts, and validation. |
| `ask` | Consequential reads, writes, and commands prompt interactively or pause for your coding agent. | You want to inspect each consequential step, especially on a first run. |

<Warning>
  **Command approval is not an operating-system sandbox.**

  An approved project command can have normal filesystem and network effects. Read the exact program, arguments, and working directory before approving it.
</Warning>

## Know which configuration owns each rule

| File | What it controls | Boundary |
| - | - | - |
| `~/.relai/config.toml` | Your global profile, global path rules, UI preference, and managed connection settings | Machine-user file; keep private |
| `.relai/config.toml` | Project registration, target mappings, and additional read/write restrictions | Cannot select a profile or loosen global rules |
| Command line | `--permissions auto\|accept_edits\|ask` | Overrides the profile for one invocation |

Resume resolves the profile again. Repeat the override when you need the same boundary, for example `relai init --resume --permissions ask`.

## Restrict project paths

Read and write rules use Gitignore-style patterns relative to the repository root. A present `allow` list is complete; `allow = []` allows nothing. Global and project allowlists intersect, while all deny rules combine. Denials and built-in protections always win.

```toml theme={"system"}
[permissions.read]
deny = ["src/private/**"]

[permissions.write]
deny = ["src/generated/**"]
```

Set `[permissions] profile` only in `~/.relai/config.toml`, never in the project file.

<Note>
  **Two similarly named files have different scope.**

  RELAI does not read `.relaiignore`. `.relai-snapshotignore` affects only source text sent to Agent Optimizer: matching files stay in the optimizer worktree for runtime access and are not deleted. It does not change ordinary workflow permissions.
</Note>

## Keep credentials and runtime values separate

<CardGroup cols={2}>
  <Card title="~/.relai/credentials.json">
    OAuth access and refresh tokens are plaintext in a user-only file: mode `0600` on Unix and a user-only ACL on Windows. They are not stored in config or CLI logs. Anyone who can read files as your user can read them, so never share or commit this file.
  </Card>

  <Card title=".relai/simulator.env">
    Ignored local values are deliberately forwarded to the Harbor agent phase during simulation and optimization. Store only values the tested agent or its tools need, and keep them out of chat and Git.
  </Card>
</CardGroup>

RELAI blocks secret environment files, package-registry credentials, SSH and cloud credentials, private keys, and its local config and simulator-env files. A workflow agent may read `.env.example` as a template, but cannot write or mount it. Add project-specific secret paths to `permissions.read.deny`.

<Card title="Ready to initialize?" href="/quickstart#1-initialize-the-repository">
  Use the profile and path boundary you chose while RELAI builds the shared project runtime.
</Card>

## User configuration reference

See [User configuration](/cli/configuration) for terminal theme settings and the
global TOML configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.