Skip to content
AndonDocs
GitHub
Look something up

The agent's config file

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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.

On this page
View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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