Configuration

Locations and precedence#

Radian reads one user configuration file. The first hit wins:

1. --config <FILE>.
2. The RADIAN_CONFIG environment variable.
3. ~/.radian/config/config.toml, or $RADIAN_HOME/config/config.toml when RADIAN_HOME is set.

A missing file is an empty configuration. Nothing creates it except the first start: on first start radian writes a commented template at the default path only. An explicit --config or RADIAN_CONFIG path is never created; a typo there stays an error, not a new file.

A project may hold <workspace>/.radian/config.toml. That file holds only [permissions] profile = "workspace". A value of full warns and has no effect: a project can only narrow the tier, never widen it. [sandbox] keys in a project file are refused by name; other project keys are skipped and named. Project skills and project servers load only when you trust the project. Untrusted projects still contribute context files as data. Pass --trust to trust one run, --no-trust to distrust one run; neither writes to disk. Confirm the trust prompt once to save it.

The command line always wins over the file. For the provider the full order is: --provider, then the resumed session route, then model.provider, then openai-compatible. Startup prints [config] <path|none> and names ignored keys, never values.

When a change applies#

File keys apply at startup: change the file and start a new session. Three settings also change inside a session through slash commands, and take effect at the next turn boundary, never mid-turn: the model route (/model), the thinking level (/thinking), and the approval answers (/auto). The theme (/theme) applies at once and writes back to the file.

schema_version#

schema_version = 1

[model]#

[model]
provider = "openai-compatible"
model = "gpt-5"
context_window = 200000
retries = 3

[model.headers]
x-tenant = "team"

[providers.<name>]#

Named endpoints. model.provider = "<name>" selects one. The key is stored under the same name in auth.json, so each endpoint has its own slot.

The name uses letters, digits, -, and _ only, and must not shadow a built-in provider. Unknown keys under a name are skipped and named. See providers for login and routing.

[providers.office]
kind = "openai-compatible"
base_url = "https://models.office.example/v1"

[permissions]#

The command line (--profile, --approval, --yes) always wins over this section. See permissions for tiers, prompts, and the sandbox.

[permissions]
profile = "workspace"
approval = "on-ask"

[sandbox]#

Only the user file may set this section. Names here pass through to sandboxed children; values never do.

Sandboxed children otherwise start from a fixed list: PATH, HOME, LANG, TERM, TMPDIR, USER, LOGNAME, SSL_CERT_FILE, SSL_CERT_DIR, and the six HERDR_* pane coordinates. No key or token reaches a child unless you name its variable here. An unsandboxed shell gets no such filtering, but the same list still gates what the model-run command inherits.

[sandbox]
allow_unix_sockets = ["~/.run/agent.sock"]
allow_env = ["MY_TOKEN_NAME"]

[hooks]#

User-level command hooks: three events, each a list of { matcher, hooks } entries. A matcher is a regular expression over Radian tool names, anchored to the whole name (shell|write names two tools); *, an empty matcher, or a missing matcher matches every tool. Each hook is { type = "command", command, timeout }. The command runs as /bin/sh -c inside the session sandbox when one is enforced; timeout is seconds (60 when unset or 0). PreToolUse exit 2 denies the call; other failures fail closed.

Anything outside this shape is skipped with one line, never refused: unknown event names, a type other than "command", non-command handler keys, an empty command, a bad timeout.

[[hooks.PreToolUse]]
matcher = "shell|write"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "make lint"
timeout = 30

[hooks]
intent_stop = true

[skills]#

See skills for discovery order and trust.

[skills]
builtin = true
disabled = ["review"]
extra_paths = ["~/.claude/skills"]

[memory.injection]#

The rest of the injection table (memory.injection.enabled, memory.injection.max_tokens, memory.injection.global_budget, memory.injection.project_budget, memory.injection.overflow) is recognized and interpreted as the documented default, and named on the startup line. See memory for scopes and injection.

[memory.injection]
additions = true
addition_budget = 500

[control]#

[integrations]#

[compaction]#

[compaction]
auto = true
thinking = "low"

[tui]#

Display preferences never refuse the file: unknown keys and wrong types warn and fall back, except an over-wide brand. They apply at startup: change the file and start a new session. The theme also switches at once through /theme, which writes the choice back to the file.

[tui]
theme = "dark"
input_style = "lines"

[tui.display]
reasoning = "collapsed"
tool_output = "errors"

[[tui.footer.rows]]
left = ["model", "context"]
right = ["usage"]

[mcp]#

Two spellings, same servers as --mcp-config: mcp.servers entries (id, command, args, inherit_env), or mcp.mcpServers.<name> tables (command plus args or a url). Remote entries warn and never start. mcpServers entries inherit HOME unless inherit_env says otherwise. Both spellings together are an error; duplicate ids are refused. The command line --mcp-config merges with this section; a shared id uses the command line entry with one warning. See mcp for the server rules.

[[mcp.servers]]
id = "search"
command = "search-server"
args = ["--fast"]
inherit_env = ["HOME"]

[shell]#

This section has no live keys. Every key, including the removed shell.auto_background_secs, warns once and is ignored. Background runs start only with an explicit background: true.

Secret references#

The file never holds a secret value. A sensitive key (api_key, apikey, token, secret, password, passwd, authorization, in any letter case) must be a reference table, and only from = "env" exists in this version. model.api_key is refused outright: store the key with radian login instead.

A bare string on a sensitive key is refused. A secret-looking string anywhere else is refused too: values starting with sk-, sk_, xoxb-, ghp_, AKIA, Bearer , or a 40-plus character run of letters, digits, _, -. Every refusal names the key path, never the value.

Credentials live in auth.json instead. A key value there may reference the environment: $NAME or ${NAME} resolves from the entry env object first, then the process environment. A missing variable is an error naming the provider and the name. !command keys are refused and never run. See providers for login and environment for the variable rules.

Migration#

radian config import-pi --from <DIR> drafts a file from a Pi agent directory: the draft on stdout, the mapping report on stderr. --write saves to the configuration path and refuses an existing file. Nothing is written without --write. radian config import-claude --claude-home <DIR> --project <DIR> drafts from Claude Code files, including skill files and AGENTS.md. Its --write saves every file and skips anything that exists, one report line each. At least one of --claude-home and --project is required. See cli for flags and exit codes, pi-migration for the Pi mapping table.

A fresh version mismatch behaves like this: an unknown top-level field or an unknown nested field is accepted and ignored — the write-back must preserve it or refuse, never drop it silently. A newer schema_version reads read-only with a warning. An older schema_version is refused; migration runs only through the explicit import commands above.

Errors you will see#