The agent's config file
Each machine’s agent keeps its settings in one JSON file, written by andon setup and changed by the andon commands.
You rarely edit it by hand: use it to look something up, or to change a key that has no command.
Every key below is checked against the code by a test (apps/agent/src/reference-docs.test.ts). The policy object
has its own page.
Where it is
| What | Where |
|---|---|
| The config file | ~/.config/andon/config.json, written with mode 0600 (it holds the hook token). ANDON_CONFIG_DIR moves the folder. |
| A second agent’s config | ~/.config/andon/profiles/<name>/config.json, for an agent enrolled with another board (andon --profile <name> …). |
| The agent’s state | ~/.local/state/andon (stateDir): runs, harnesses, the agent’s own Codex and Gemini CLI homes. |
| The service’s logs | macOS: ~/Library/Logs/andon. Linux: ~/.local/state/andon/logs (under XDG_STATE_HOME when set). |
| The machine’s sign-in | Not in this file: in the Keychain, the Secret Service, or credentials.json next to the config (credentialBackend). |
After you edit the file, restart the agent so it reads every key: andon install-service. The policy is read again
before each run without a restart.
Keys
| Key | Default | What it is |
|---|---|---|
configVersion |
set by the agent | The file’s format version. The agent migrates older files and rewrites them. |
machineId |
set at setup | This machine’s id on the board. |
orgId |
set at setup | The org the machine belongs to. |
slug |
set at setup | The machine’s short name on the board. |
machineName |
set at setup | The machine’s display name. |
boardUrl |
set at setup | The board it enrolled with. |
apiUrl |
set at setup | The Andon server the agent talks to. A config from a board on Supabase has supabaseUrl and supabaseAnonKey instead: the agent no longer connects to Supabase and says so in one line; re-enroll with andon setup --url <board>. |
credentialBackend |
keychain on macOS, else file |
Where the sign-in is kept: keychain, secret-service or file. Setup picks the Secret Service on a Linux desktop that has it. |
projectsRoot |
~/Projects |
Where new repositories, clones and worktrees go. It must be inside the policy’s workspaceRoots. |
scratchRoot |
~/Andon |
Where scratch folders go (runs that need no repository). It must be inside workspaceRoots. |
hookPort |
7777 |
The local port of the agent’s hook server (1024 to 65535). A second agent gets its own. |
hookToken |
set at setup | The CLI’s secret for the agent’s hook server (/cli/*). A run or a conversation never sees it: each gets a token of its own derived from it, which acts as that run or conversation only. |
bins |
see below | The programs the agent runs, by name or path. |
capabilityTags |
[] |
Extra capability tags this machine reports, for recipes that require them. |
accounts |
[] |
Claude, Codex and Gemini CLI accounts. Edit with andon accounts. |
providers |
[] |
Model providers this machine has a key for. Edit with andon providers. The keys are in the credential store. |
llm.backend |
auto |
Machine mode (model calls the app hands this machine): anthropic (Claude), direct (Gemini), gateway (the Vercel AI Gateway), or auto (Claude with an Anthropic key, else Gemini with a Gemini key, else the gateway). Edit with andon llm backend; the keys are in the credential store (andon llm key). |
harnesses |
[] |
Harnesses imported here. Edit with andon harness. |
launcher |
tmux |
How a run’s session starts. tmux: Claude in the agent’s tmux, shown in an Orca terminal when Orca is installed. direct: never Orca (git worktrees and tmux); also used when Orca isn’t installed. orca-pty: straight in an Orca terminal, without tmux. |
scanRoots |
[] |
Where the repository scan looks (depth 4). Edit with andon repos. |
tmuxSocket |
andon-<slug> |
The agent’s own tmux socket name. |
stateDir |
~/.local/state/andon |
The agent’s state folder. |
decisionTimeoutSec |
1800 |
How long a run’s permission request or question waits for an answer on the board before it expires (10 s to 24 h). |
pipelinePollSec |
120 |
How often the machine checks CI on its pull requests (1 to 3600). |
stallAfterMin |
20 |
An interactive run with no hook and a still terminal for this long is settled as idle, or flagged as needing input. 0 turns it off. |
backgroundWaitSec |
1200 |
A turn that ends with background tasks still running keeps the run working; the pane is read again every this many seconds. |
lostConnectionRetries |
3 |
A turn cut off by a lost API connection is carried on by the agent up to this many times in a row (0 to 10; 0 asks you instead). |
lostConnectionRetrySec |
30 |
The first wait before carrying on; each next wait is twice the last. |
usageCheckMin |
15 |
How often each Claude account is asked for its usage, in minutes (0: never). |
syncIntervalSec |
300 |
How often the agent syncs with the board between full repository scans. |
ciTimeoutSec |
3600 |
How long the machine waits for a pull request’s checks. |
reviewSettleSec |
300 |
After a clean review, how long review bots get to post before the run hands back. |
captureToken |
none | The capture token andon add sends. Set with andon capture-token. |
apiToken |
none | A personal API token the card commands send. Set with andon api-token. |
tunnel |
see below | Previews and the direct terminal. Set with andon tunnel. |
policy |
see policy | What this machine allows. |
trustedKeys |
[] |
Member device keys whose signed commands this machine accepts. Edit with andon keys. |
bins
Each is a command name looked up on PATH, or a full path.
| Key | Default | Used for |
|---|---|---|
bins.orca |
orca |
Orca workspaces and terminals. |
bins.claude |
claude |
Claude Code. |
bins.codex |
codex |
Codex. |
bins.gemini |
gemini |
Gemini CLI. |
bins.tmux |
tmux |
Sessions without Orca. |
bins.git |
git |
Worktrees, branches and commits. |
bins.gh |
gh |
Pull requests. |
bins.ffmpeg |
ffmpeg |
Output previews (images and video). |
bins.ffprobe |
ffprobe |
Output sizes and durations. |
bins.open |
open on macOS, else xdg-open |
Revealing an output on the machine. |
bins.tailscale |
tailscale |
The Tailscale tunnel. Setup points it at the macOS app’s CLI when tailscale isn’t on PATH. |
bins.cloudflared |
cloudflared |
The Cloudflare tunnel. |
bins.chrome |
none | The headless Chrome or Chromium that captures preview frames. Unset: the usual install places, or ANDON_CHROME. |
tunnel
| Key | Default | What it is |
|---|---|---|
tunnel.provider |
off |
off, tailscale or cloudflare. Off: nothing on this machine is reachable from outside, and previews are off. |
tunnel.terminal |
true |
The board opens this machine’s terminals directly through the tunnel. |
tunnel.terminalPort |
7778 |
Where the direct terminal listens on 127.0.0.1. |
tunnel.decided |
false |
Whether setup has asked about the tunnel (a No is remembered too). |
