Configuration & permissions

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

Inspect the boundary before a workflow

Ask your coding agent
Run in terminal

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.

After reviewing the boundary, initialize with your chosen profile. This command creates and validates project files; it is not a read-only inspection.

relai init --permissions ask

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.

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.

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.

[permissions.read]
deny = ["src/private/**"]

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

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

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.

Keep credentials and runtime values separate

~/.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.

.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.

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.

Ready to initialize?

Use the profile and path boundary you chose while RELAI builds the shared project runtime.

User configuration reference

See User configuration for terminal theme settings and the global TOML configuration.

Get started

Build evidence

Evaluate & improve

Learn & support

Command reference

Configuration & permissions

Inspect the boundary before a workflow

Choose an approval profile

Know which configuration owns each rule

Restrict project paths

Keep credentials and runtime values separate

~/.relai/credentials.json

.relai/simulator.env

Ready to initialize?

User configuration reference

​Inspect the boundary before a workflow

​Choose an approval profile

​Know which configuration owns each rule

​Restrict project paths

​Keep credentials and runtime values separate

~/.relai/credentials.json

.relai/simulator.env

Ready to initialize?

​User configuration reference

Inspect the boundary before a workflow

Choose an approval profile

Know which configuration owns each rule

Restrict project paths

Keep credentials and runtime values separate

User configuration reference