Configuration

Agent Relay reads configuration from two places, in order of increasing priority:

.agent-relay/config.toml in the current repo — for project defaults you want to commit to the repository.
Environment variables — for ephemeral overrides and CI usage.

Anything you don't set falls back to a built-in default. There is no global user-level config file; every setting is repo-scoped.

config.toml — the per-repo file

Drop a config.toml into the .agent-relay/ directory (it sits next to sessions/). The example below shows every available key with its default — copy what you need, delete what you don't.

toml

# .agent-relay/config.toml
 
[default]
# Which agent to use when `agent-relay run` is called with no agent argument.
agent = "claude-code"
 
# Hard cap on turns per session. `0` means unlimited.
max_turns = 0
 
# Stream watcher output inline by default. Equivalent to passing --watch.
watch = false
 
# Disable ANSI colors in Agent Relay's own output.
no_color = false
 
[sessions]
# Directory (relative to the repo root) where sessions are written.
dir = ".agent-relay/sessions"
 
# Compress turn artifacts older than this many days into a single archive.
# `0` means never compress.
compress_after_days = 0
 
[handoff]
# When a checkpoint is written, also recommend this agent as the next runner.
# Leave empty to let Agent Relay pick based on the previous agent.
recommend = ""
 
# Maximum decisions kept in the resume packet. Older decisions are summarized.
max_decisions = 12
 
[metrics]
# Which currency to render cost figures in.
currency = "USD"
 
# Override the bundled rate table at this path. Useful for negotiated rates.
rate_table = ""
 
[agents.claude-code]
# Per-agent overrides. The key matches an adapter name from `discover`.
binary = "claude-code"
extra_args = []
 
[agents.codex]
binary = "codex"
extra_args = []

Environment variables

Every config.toml key has a matching environment variable. The mapping is mechanical: uppercase, prefix with AGENT_RELAY_, replace dots with double underscores.

Variable	Maps to	Example
`AGENT_RELAY_DEFAULT__AGENT`	`[default] agent`	`claude-code`
`AGENT_RELAY_DEFAULT__MAX_TURNS`	`[default] max_turns`	`12`
`AGENT_RELAY_DEFAULT__WATCH`	`[default] watch`	`true`
`AGENT_RELAY_SESSIONS__DIR`	`[sessions] dir`	`/tmp/agent-relay-sessions`
`AGENT_RELAY_HANDOFF__RECOMMEND`	`[handoff] recommend`	`codex`
`AGENT_RELAY_METRICS__CURRENCY`	`[metrics] currency`	`EUR`

Two non-keyed variables also exist:

Variable	Effect
`AGENT_RELAY_CONFIG`	Path to an alternative config file. Replaces — does not merge with — `.agent-relay/config.toml`.
`AGENT_RELAY_NO_TELEMETRY`	Set to `1` to forcibly disable any future telemetry. Currently a no-op (Agent Relay has no telemetry); set it now and future versions will respect it.
`NO_COLOR`	The cross-tool standard. If set to anything non-empty, behaves the same as `AGENT_RELAY_DEFAULT__NO_COLOR=true`.

Precedence

For any single setting, Agent Relay resolves in this order — later sources override earlier ones:

Built-in default.
.agent-relay/config.toml in the repo.
Environment variables.
Command-line flag on agent-relay run (or any subcommand).

A flag always wins, an env var always beats config.toml, and config.toml always beats the built-in default.

Per-agent settings

The [agents.<name>] table lets you point an adapter at a non-default binary or pass extra arguments to every invocation. Useful for:

Calling a wrapper script instead of the agent's own CLI
Pinning a specific version with extra_args = ["--version-pin", "1.7.4"]
Routing through a proxy or sandbox

toml

[agents.codex]
binary = "/opt/sandboxes/codex-wrapper.sh"
extra_args = ["--budget", "5000"]

Validation

Run the bundled validator to check your config for typos and unknown keys:

terminal

agent-relay config check

Reports unknown keys, malformed TOML, and references to adapters that aren't installed (with --strict, treats those as errors).

Installation

Install Agent Relay before reaching for config.toml.

FAQ

Common questions about telemetry, agents, platforms, and licensing.