Skip to content
AndonDocs
GitHub
Look something up

Machine policy

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

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