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), 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).
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 policyprints each part of the policy as a row: ✓ allows, ~ limits, ✗ blocks, with the command that changes it.andon policy showprints the wholepolicyobject 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
allowGhRepoCreateoff. - 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 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). |
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. | 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 offremoves 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 onputs 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_workspacecommand. The workspace must be insideworkspaceRoots, andremove_workspacemust be inacceptCommands. The path being removed must also be the one that was checked. Otherwise the deletion fails with the reason and the workspace stays. Withsignatures.modeset torequire, a deletion Andon scheduled is refused too, because no member’s device signed it, unlesssignatures.unsignedKindslistsremove_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.jsonis kept, including the Yes an earlier agent gave: turn it off with/chrome. Turn the browser on with/chromein that login, or add--chrometo 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 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. |
