# Machine policy

A machine's local policy decides what Andon may do on it: which recipes run, how far a run's permissions go, whether it
merges, which agent CLIs it starts. The board can ask for anything; the machine's policy is the last word. It lives in
the `policy` object of the agent's config file ([agent config](https://andon-docs.pages.dev/reference/agent-config.md)), and you change it on the machine with
`andon policy`. In the desktop app, Settings → Machines has a button for each fix on the computer it runs on
([desktop app](https://andon-docs.pages.dev/guide/desktop-app.md#fix-this-machines-policy-in-the-app)).

The running agent reads the policy again before it starts each run, so a change applies to the next run without a
restart.

Every subcommand and key below is checked against the code by a test (`apps/agent/src/reference-docs.test.ts`).

## See the policy

- `andon policy` prints each part of the policy as a row: ✓ allows, ~ limits, ✗ blocks, with the command that changes
  it.
- `andon policy show` prints the whole `policy` object as JSON.

## Presets

`andon policy preset locked|standard|open` (or `andon setup --preset …`) sets four keys at once and leaves every other
key as it is.

| Preset | `recipes.mode` | `allowAutoMerge` | `allowNewRepo` | `terminalInput` |
|---|---|---|---|---|
| `locked` | `approve` | `false` | `false` | `false` |
| `standard` | `approve` | `true` | `true` | `true` |
| `open` | `trust_org` | `true` | `true` | `true` |

- **Locked:** every recipe needs approving here, no auto merge, no new repositories, and the board can't type into this
  machine's sessions. It also turns `allowGhRepoCreate` off.
- **Standard:** the schema's defaults. It also approves the org's current recipes, so only a new or edited recipe needs
  approving here.
- **Open:** runs any recipe from the org.

Setup applies Open unless you pick another preset or pass `--preset`. Standard and Locked pin each recipe to its hash,
so an edited recipe needs `andon policy approve <slug>` on the machine.

## Subcommands

| Command | What it does | Key |
|---|---|---|
| `andon policy approve <recipe-slug>` | Show a recipe (its prompt, system prompt and tools) and approve it at its current hash. An edit to it needs approving again. | `recipes.approved` |
| `andon policy recipes approve\|trust-org` | `approve`: only recipes approved here run. `trust-org`: any recipe from the org runs. | `recipes.mode` |
| `andon policy trust-org` | Short for `andon policy recipes trust-org`. | `recipes.mode` |
| `andon policy permission-mode <mode>` | The most a run may use: `plan`, `dontAsk`, `manual`, `acceptEdits` or `auto`. A run that asks for more runs in this mode. | `maxPermissionMode` |
| `andon policy tools "<list>"` | The tools a recipe may have pre-approved here, space-separated: `"Read Edit Bash(git:*) mcp__andon__*"`. | `allowedToolsCeiling` |
| `andon policy auto-merge on\|off` | Whether this machine merges a reviewed pull request when its team turns auto merge on, and a card's branch into the base where the repository has no GitHub remote. Off: reviewed PRs wait as "Ready to merge", and branches stay unmerged. | `allowAutoMerge` |
| `andon policy auto-push on\|off` | Whether a card run that ends with unpushed commits, on a team that reviews automatically, gets its branch pushed and a PR opened. Off also keeps Andon from merging a card's branch where the repository has no GitHub remote; the card then stays out of Done until the branch is merged or pushed. | `autoPush` |
| `andon policy new-repos on\|off` | Whether runs may clone repositories and start new ones from a folder. | `allowNewRepo` |
| `andon policy terminal-input on\|off` | Whether replies and decisions from the board are typed into this machine's sessions. | `terminalInput` |
| `andon policy executors claude,codex,gemini` | Which agent CLIs may run here, comma-separated. A run for another one fails with a policy error. | `allowedExecutors` |
| `andon policy runtimes orca,terminal` | Where runs may live: Orca workspaces, git worktrees with tmux (`terminal`), or both. | `allowedRuntimes` |
| `andon policy extra-args accept\|refuse` | Whether card sessions take the extra CLI arguments set on the board (**Settings → Machines**, the machine, **Extra arguments**). Only the flags listed under [Extra arguments](https://andon-docs.pages.dev/machines/orca-or-direct.md#extra-arguments) are taken; any other is refused either way. | `extraArgs` |
| `andon policy extra-args --clear-retired` | Drop the extra arguments an older agent kept in this file. | `retiredExtraArgs` |
| `andon policy board-extra-args on\|off` | The old name of `extra-args accept\|refuse`. | `extraArgs` |
| `andon policy auto-update on\|off` | Whether the agent installs the board's signed build once a day. Off: update with `andon update`. | `autoUpdate` |
| `andon policy cli-skill on\|off` | The `use-andon` skill for coding agents on this machine ([below](#the-use-andon-skill)). | `cliSkill` |
| `andon policy context-summary on\|off` | Whether Claude writes a short summary (no tools) of an imported card's branch and last session. | `contextSummary` |
| `andon policy auto-build-planner on\|off` | Whether this machine's Claude or Codex may write Autopilot's plans (no tools) when it's picked as the planner, or when it holds the cards' repositories. Off: the team's planner falls back to Gemini, or one card a PR. | `autoBuildPlanner` |
| `andon policy recipe-detect on\|off` | Whether this machine's Claude or Codex may pick the recipe of a card that has none (no tools) when it's moved to run. | `recipeDetect` |
| `andon policy improve-notes on\|off` | Whether this machine's Claude may rewrite a card's notes (no tools) when someone asks on the board. | `improveNotes` |
| `andon policy llm-serve on\|off` | Whether the app may hand this machine model calls (machine mode) to run with its own Anthropic, Gemini or AI Gateway key (`andon llm key`). Off by default. | `llmServe` |
| `andon policy drive-answers on\|off` | Whether, while Andon drives, this machine's Claude may answer the questions its own runs ask (no tools) when no AI backend can answer: no Anthropic, Gemini or AI Gateway key, and no machine serving model calls. | `driveAnswers` |
| `andon policy orchestrator on\|off` | Whether the board's chat may use this machine. | `orchestrator` |
| `andon policy coordinator on\|off` | Whether a coordinated workstream may pick this machine to host its coordinator. Off by default; the orchestrator must be on too. | `coordinator` |
| `andon policy orca-import off\|worktrees\|worktrees+sessions` | What the board may import from Orca on this machine: nothing, worktrees, or worktrees and their sessions. | `orcaImport` |
| `andon policy terminal-app <app>` | macOS: the app **Show in Terminal** opens (`Terminal`, `iTerm`, `Ghostty`…). | `terminalApp` |
| `andon policy auto-open-terminal on\|off` | Whether an interactive run in a terminal opens a window by itself as it starts. | `autoOpenTerminal` |
| `andon policy signatures require\|off` | `require`: this machine acts only on commands and runs signed by a member device approved here (`andon keys approve`). Runs Andon starts by itself (Autopilot, pipelines, review rounds) are then refused. | `signatures.mode` |
| `andon policy preset locked\|standard\|open` | Apply a [preset](#presets). | four keys |
| `andon policy show` | Print the policy as JSON. | |

## The use-andon skill

The agent puts a skill named `use-andon` into the user skill folder of every coding agent on the machine, so a session
in any repository can use Andon through `andon`: add, read and steer cards, put a plan on the board, say what needs
you, and check this machine's agent. It's on by default (`cliSkill: true`).

- `andon policy cli-skill off` removes it from every coding agent on the machine and keeps it off: setup, updates and the
  agent's start no longer write it.
- `andon policy cli-skill on` puts it back.

The agent keeps one copy in its own data folder (`~/.local/share/andon/skills/use-andon`, or under `XDG_DATA_HOME`)
and links it into each agent's folder. It writes a folder only for an agent that is installed (its home folder exists):

| Folder | Read by |
|---|---|
| `~/.claude/skills/use-andon` (under `CLAUDE_CONFIG_DIR` when set) | Claude Code |
| `~/.agents/skills/use-andon` | Codex, Gemini CLI, Cursor, OpenCode, Qwen Code, Kimi, Devin, Amp, Factory Droid, Roo Code |
| `~/.copilot/skills/use-andon` (under `COPILOT_HOME` when set) | GitHub Copilot |
| `~/.gemini/config/skills/use-andon` | Antigravity |
| `~/.kiro/skills/use-andon` | Kiro |
| `~/.hermes/skills/use-andon` (under `HERMES_HOME` when set), and each Hermes profile's `skills/` | Hermes Agent |

An agent that also reads `~/.claude/skills` (Cursor, OpenCode, Kimi, Amp) doesn't count for `~/.agents/skills`
while Claude Code's copy is there, so it doesn't list the skill twice. A folder of that name that isn't the agent's (a
skill of your own) is left alone. A skill the agent wrote under the old name `andon` is removed.

## What the machine checks itself

The board and the database can ask for anything, so the agent checks what they hand it against this policy before it
acts:

- **Previews.** A run's output is uploaded only if the file is a regular file inside the run's workspace (or its
  card's mock folder) *and* inside `workspaceRoots`. A workspace path the database names outside those roots isn't
  enough, so a row can't point the agent at a file elsewhere on the machine and have it uploaded. Frames the agent
  captured itself, in its own run folder, are the one exception.
- **Workspace deletions.** When a card reaches Done, its workspace deletion follows the same rules as the
  `remove_workspace` command. The workspace must be inside `workspaceRoots`, and `remove_workspace` must be in
  `acceptCommands`. The path being removed must also be the one that was checked. Otherwise the deletion fails with
  the reason and the workspace stays. With `signatures.mode` set to `require`, a deletion Andon scheduled is refused
  too, because no member's device signed it, unless `signatures.unsignedKinds` lists `remove_workspace`. Remove the
  workspace from the card instead (**Remove workspace**, which is signed).
- **Signed runs.** A signed run carries a hash of the card's title, notes, inputs and prompt as they were when Run was
  pressed. If the card changes before the machine takes the run, a machine that requires signatures refuses it. Press
  Run again to sign the new text. Signatures from a board that predates the hash are refused the same way, so reload
  the board after updating.
- **Claude in Chrome.** Before a card run, the agent answers Claude's *Claude in Chrome extension detected* screen
  with *No, keep browser tools off* (`claudeInChromeDefaultEnabled: false`). Starting a run from the board doesn't
  give it your signed-in browser. An answer already in that login's `.claude.json` is kept, including the *Yes* an
  earlier agent gave: turn it off with `/chrome`. Turn the browser on with `/chrome` in that login, or add `--chrome`
  to the machine's extra arguments for card runs.

## Keys

The `policy` object in the config file. Keys with a subcommand are changed with it; for the others, edit the file
(`andon policy show` prints it, [agent config](https://andon-docs.pages.dev/reference/agent-config.md) says where it is).

| Key | Default | What it does |
|---|---|---|
| `recipes.mode` | `approve` | `approve`: only recipes approved here run. `trust_org`: any recipe from the org. |
| `recipes.approved` | `{}` | Recipe slug → the hash approved here. |
| `maxPermissionMode` | `auto` | The highest permission mode a run gets: `plan`, `dontAsk`, `manual`, `acceptEdits` or `auto`. |
| `allowedToolsCeiling` | `Read`, `Edit`, `Write`, `Glob`, `Grep`, `Bash(git:*)`, `Bash(npm:*)`, `Bash(pnpm:*)`, `mcp__andon__*` | The tools a recipe may pre-approve; anything else it lists is dropped. |
| `workspaceRoots` | `~/Projects`, `~/orca`, `~/Andon` | Where runs may work, clone and scan, and the only folders outputs are uploaded from and workspaces are deleted in. `andon repos add` adds a folder after asking. |
| `allowNewRepo` | `true` | Runs may clone repositories and start new ones. |
| `allowGhRepoCreate` | `false` | A run that starts a new repository may also create it on GitHub (`gh repo create`). |
| `terminalInput` | `true` | The board may type replies and decisions into sessions here. |
| `acceptCommands` | every kind | The board commands this machine acts on: `send_text`, `decide`, `interrupt`, `stop`, `focus`, `reveal_output`, `sync`, `remove_workspace`, `release_session`. Without `remove_workspace`, Done doesn't delete workspaces here either. |
| `maxAttachmentBytes` | 25 MB | The largest file a run may attach or publish, in bytes. |
| `skills.deny` | `[]` | Connectors and skills a run here must not have. While the list isn't empty and the connectors can't be detected, runs are refused. |
| `harnesses.mode` | `approve` | `approve`: a run's harness must be approved here (`andon harness approve`). `trust_org`: any harness the board attaches. |
| `harnesses.approved` | `{}` | Harness slug → the hash approved here. |
| `memory.reflect` | `true` | Not read by the agent: a finished run is reflected on only with `andon memory reflect`. |
| `orcaImport` | `worktrees+sessions` | What the board may import from Orca: `off`, `worktrees` or `worktrees+sessions`. Importing is still a tick on the board. |
| `allowAutoMerge` | `true` | This machine may merge a reviewed PR when its team turns auto merge on, and a card's branch into the base without a PR. |
| `autoPush` | `true` | A card run that ends with unpushed commits gets its branch pushed and a PR opened. |
| `autoUpdate` | `true` | Install the board's signed agent build once a day. |
| `cliSkill` | `true` | Keep the `use-andon` skill in every coding agent's skill folder. |
| `contextSummary` | `true` | Summarise an imported card's branch and last session with Claude (no tools). |
| `autoBuildPlanner` | `true` | This machine's Claude or Codex may write Autopilot's plans (no tools). |
| `recipeDetect` | `true` | This machine's Claude or Codex may pick a card's recipe (no tools). |
| `improveNotes` | `true` | This machine's Claude may rewrite a card's notes on request (no tools). |
| `driveAnswers` | `true` | This machine's Claude may answer its own runs' questions while Andon drives (no tools). |
| `llmServe` | `false` | The app may hand this machine model calls (machine mode, `LLM_PROVIDER=machine`) to run on the AI SDK with its own key (`andon llm key`). Only the prompt and the answer travel. |
| `orchestrator` | `on` | The board's chat may use this machine. |
| `orchestratorMaxPermissionMode` | `dontAsk` | The chat's permission ceiling: `plan` or `dontAsk`. A wider value reads as `dontAsk`. Under `plan`, Codex and Gemini CLI conversations only get the orch_* tools that read the board and `orch_open`. |
| `orchestratorTurnTimeoutSec` | `300` | Seconds one chat turn may take before it's stopped (10 to 3600). |
| `coordinator` | `off` | A coordinated workstream may use this machine for its coordinator. A coordinator spends turns with nobody watching, so a machine opts in. It runs under `orchestratorMaxPermissionMode` with only the coord_* tools (under `plan`, only the two that read). |
| `coordinatorTurnTimeoutSec` | `300` | Seconds one coordinator turn may take before it's stopped and counted as failed (10 to 3600). |
| `allowedExecutors` | `claude`, `codex`, `gemini` | The agent CLIs that may run here. Codex and Gemini CLI chat conversations follow it too. |
| `allowedRuntimes` | `orca`, `terminal` | Where runs may live. A run that asks for `auto` gets the machine's own runtime if it's allowed, else the other. |
| `extraArgs` | `accept` | Take the board's extra CLI arguments for card sessions, or `refuse` them. |
| `retiredExtraArgs.claude`, `retiredExtraArgs.codex`, `retiredExtraArgs.gemini` | `[]` | Extra arguments an older agent kept in this file. Each applies only while the board sets none for that CLI. |
| `terminalApp` | `Terminal` | macOS: the app **Show in Terminal** opens. |
| `autoOpenTerminal` | `false` | Open that window by itself when an interactive terminal run starts. |
| `signatures.mode` | `off` | `require`: act only on what an approved member device signed. A signed run must match the card's current content, and Done doesn't delete workspaces here unless `unsignedKinds` lists `remove_workspace`. |
| `signatures.unsignedKinds` | `sync`, `repo_icons`, `workspace_context`, `close_terminal` | Commands accepted unsigned even when signatures are required: they only read or tidy up. |
