# 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](https://andon-docs.pages.dev/reference/policy.md).

## 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](https://andon-docs.pages.dev/reference/policy.md) | 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). |
