Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

Orca or direct

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 runs each card in one of two places. With Orca installed, a run gets an Orca worktree and terminal. Without it, the machine runs in direct mode: a git worktree, and the coding agent in the agent’s own tmux. Orca is optional.

What a machine needs

Tool Why Install
git a worktree for each card xcode-select --install on a Mac, or your distro’s git
tmux the session each run lives in brew install tmux, apt-get install tmux, dnf install tmux, pacman -S tmux
Claude Code cards on Claude Code offered by setup on a Mac with the Claude app, or --install-claude; then claude auth login
Codex CLI cards on Codex npm install -g @openai/codex (or brew install codex), then codex login
Gemini CLI cards on Gemini CLI npm install -g @google/gemini-cli, then sign in through Andon
gh (optional) pull requests from card branches brew install gh or your distro’s package, then gh auth login

A machine needs at least one of Claude Code, Codex and Gemini CLI. The installer checks for these and enrolls the machine: Mac, Linux, Windows.

The agent looks for each CLI at every sync. Settings → Machines lists a machine’s agents under Advanced (Agents: Claude Code, Codex). A Codex card goes only to a machine that reports Codex. After you install a CLI, press Sync (the circular arrows) on the machine’s card, or wait for the next heartbeat.

On a Mac with the Claude app but no claude, setup offers to install Claude Code with Anthropic’s installer and sign it in with the account you use in the app. --install-claude installs it unattended (the sign-in then waits for you), --no-install-claude skips the question, and --yes alone never installs it. To add it later: andon setup --install-claude.

How a machine picks: Orca or a terminal

Where a card runs is not a board setting. The agent decides per run:

  1. A machine with the orca command runs cards in Orca. One without it runs them in a terminal (direct mode).
  2. A repository’s .andon/settings.json can ask for one with runtime under automation: auto (the default), orca or terminal. A run that asks for Orca on a machine without it runs in a terminal.
  3. The machine’s policy can turn either off: andon policy runtimes orca,terminal lists the ones it allows. A run that asks for one the policy turns off fails with the reason, and the card offers Run on another machine.

To keep a machine in direct mode even though Orca is installed, set "launcher": "direct" in ~/.config/andon/config.json and restart the agent.

The board labels a direct machine Direct and hides Focus in Orca and Adopt Orca worktrees for it. The run panel’s heading ends with where the run went, for example Codex · gpt-5-codex · Terminal.

Direct mode

In direct mode, and for any run in a terminal:

  • Each run gets a git worktree at <projectsRoot>/worktrees/<repo>/<branch> on its own andon-… branch. projectsRoot defaults to ~/Projects.
  • The coding agent runs in the tmux session andon-<run id> on the agent’s own socket. List them with tmux -L andon ls.
  • Every run’s session lives in that one tmux server, so if the server goes away, every run on the machine ends with it. The agent notices within 15 seconds and writes one line to its log (the socket, when the server last answered, the sessions and runs it took, and what the agent could tell about why: the process exited, or it still runs but its socket file was removed). Settings → Machines shows tmux server stopped at 15:31; 5 runs interrupted (or restarted, when a new server had already taken its place by the time the agent noticed) for a week, and andon doctor shows the last one. Each run that was still working and hadn’t opened its pull request ends Interrupted, and Needs you offers Resume (or Resume all, for several at once): see An interrupted run.
  • A run’s command doesn’t see $TMUX or $TMUX_PANE, so a bare tmux kill-server (or any bare tmux command) in a run, or in a tool the coding agent runs, reaches the default tmux server, not the agent’s. Naming the socket, tmux -L andon …, still reaches it: don’t put that in a recipe or a card.
  • The agent finds repositories by scanning its scan roots. andon repos lists and edits them.

Show in Terminal

A run in a terminal has two terminal items in its ⋯ menu:

  • Open terminal opens the board’s own terminal, in the browser on any device, attached to the run’s tmux session. What you type goes to the session; Read-only turns that off.
  • Show in Terminal opens a window on the machine itself, attached to the same session. It takes the place of Focus in Orca. The board shows it only when the machine can open a window: always on a Mac; on Linux only with a display and x-terminal-emulator; never on a server.

On a Mac the window opens in Terminal unless andon policy terminal-app <app> names another (iTerm, Ghostty, …). andon policy auto-open-terminal on opens it by itself as each interactive run starts. Closing the window detaches; the run keeps going.

When the coding agent shows its own prompt in the terminal, one the board can’t answer, the card says Claude is waiting in its terminal (or Codex, or Gemini), with Open terminal, Show in Terminal (or Focus in Orca) and Interrupt.

Choose the agent and model

The workspace’s default is under Settings → Automation: Agent (Claude Code, Codex or Gemini CLI) and Model. A team can change both under Settings → Teams → the team → Overrides. A card can change them in its properties: Agent and Model, where Default for this team follows the team.

For Codex and Gemini CLI, a model is the name the CLI takes (for example gpt-5-codex, or a gemini-… name); empty means the CLI’s own default. Changing the agent resets the model. Accounts are on Several CLI accounts.

Codex

  • One Codex home per machine. Andon runs Codex with CODEX_HOME set to ~/.local/state/andon/codex-home. It holds the sessions (so Continue resumes them), Andon’s hooks and the trusted worktrees. Your login is linked in from ~/.codex/auth.json (or $CODEX_HOME/auth.json if you set CODEX_HOME). Andon never writes to ~/.codex.
  • The first run on a machine asks you to trust Andon’s hooks. The card shows Codex is waiting in its terminal. Press Open terminal and choose Trust all and continue. Andon never answers this screen for you, and offers no Interrupt there (Escape would skip the hooks). You answer it once per machine, and again only when Andon’s hooks change.
  • Permissions come to the board like Claude’s: Codex needs a decision, the command, Codex’s reason, Allow or Deny. Each Andon permission mode maps to a Codex sandbox and approval policy, never a bypass or full-auto mode.
  • Interrupt (or Escape in Codex) ends the turn, and the card goes to Waiting for you.
  • A live session can’t switch model (Codex’s /model is a picker). Stop the session and Continue on the other model.
  • Headless runs (codex exec) can’t write .git from Codex’s sandbox, so Andon commits what Codex changed on the card’s branch when the run ends.

Gemini CLI

Gemini CLI runs a card in the run’s tmux session or headless, and can review a team’s own pull requests. Pick it as the Agent (above) or as the team’s Reviewer (search Settings for Reviewer).

  • A Gemini home per account. Andon sets GEMINI_CLI_HOME to the run’s account. The machine’s own login is ~/.local/state/andon/gemini-home; an account added with andon accounts add gemini <name> is its own home. Andon never reads or writes ~/.gemini. Sign in once per home: Gemini CLI sign-in.
  • Google’s models only. A Gemini run on a provider’s model (openrouter/…) fails with Gemini CLI runs on Google’s models only.
  • Trust. Andon trusts each card worktree for Gemini before it starts, so Gemini doesn’t ask. It never trusts someone else’s checkout, because trusting a folder loads that folder’s own .gemini/ settings, hooks and MCP servers. A Gemini review of someone else’s pull request is refused. If Gemini asks Do you trust the files in this folder?, the card says so: answer it in the terminal.
  • Permissions. Andon’s plan mode runs Gemini in its plan mode; dontAsk and manual run its default mode; acceptEdits and auto run it in auto_edit. Andon never passes yolo. In dontAsk and acceptEdits, the recipe’s allowed shell commands and edit tools run without asking. Anything else asks in Gemini’s own prompt, and the card shows that prompt with its options as buttons (Allow once, Allow for this session, No, suggest changes). No, suggest changes, like Interrupt, cancels the whole turn, and the card goes to Waiting for you: reply to say what to do instead.
  • Switching the model of a live session types /model set <model> (for this session only), then your text.
  • Headless runs (a headless card, a pipeline step, a review round) leave out every tool that would ask. They run only the shell commands the recipe allows, and edit only in dontAsk and acceptEdits; a plan run edits nothing. Andon commits what the run changed on the card’s branch when it ends.
  • Review rounds run on the team’s own pull requests only. Andon commits and pushes Gemini’s fixes before it records the round.

The machine’s policy

The machine’s local policy has the final say over what runs on it. It lives in the config file under policy.

  • andon policy prints it as rows: what each key allows or blocks, and the command that changes it.
  • andon policy show prints the raw JSON.
  • The board shows the same rows: Settings → Machines, open Advanced on the machine’s card, then Local policy, with the preset it matches. They are read-only, except in the desktop app on the computer it runs Andon on, where a row that holds something back has a button that runs its fix (Fix this machine’s policy in the app).

Presets

Setup ends by asking for a preset (--preset locked|standard|open answers it unattended). andon policy preset <name> switches later. A preset sets four things; every other key keeps its value.

Preset Recipes Auto merge New repositories (clone, Start from a folder) Terminal input from the board
Locked each needs andon policy approve <recipe> on the machine off off off
Standard the org’s current ones approved; new or edited ones need approving on the machine allowed allowed on
Open any recipe from the org allowed allowed on

Unattended, and when you press Enter at the question, setup picks Open, so editing a recipe on the board never stops this machine’s runs. Pick Standard or Locked when each recipe change should be approved on the machine first. --trust-org, --approve-current, --allow-auto-merge and --no-auto-merge adjust the preset after it is applied.

Agents and runtimes

Key Default Command What it does
allowedExecutors Claude Code, Codex and Gemini CLI andon policy executors claude,codex The agent CLIs this machine runs cards with. A card on another fails before anything is made: ’s policy doesn’t allow Codex.
allowedRuntimes Orca and terminal andon policy runtimes orca,terminal Where runs may live (see How a machine picks).
terminalApp Terminal andon policy terminal-app iTerm The Mac app Show in Terminal opens.
autoOpenTerminal off andon policy auto-open-terminal on Opens that window by itself as each interactive run starts.
extraArgs accept andon policy extra-args refuse Whether runs here take the extra arguments set on the board (below).

A refused run changes nothing on the machine, and the card offers Run on another machine. Settings → Machines shows an agent the policy turns off: Agents: Claude Code · Codex off in its policy.

The config file’s bins.claude, bins.codex, bins.gemini, bins.tmux and bins.git point at a CLI that isn’t on the agent’s PATH.

Every andon policy key is listed in andon --help.

Extra arguments

A machine can add its own flags to every coding-agent session it starts, --chrome for example.

  1. Open Settings → Machines and find the machine.
  2. Open Advanced.
  3. Under Extra arguments, type the flags for Claude Code, Codex or Gemini CLI. Only the machine’s owner can change them.

The next session picks them up, interactive and headless, but not Codex review rounds. They go on the command line after Andon’s own flags. The machine can refuse them all with andon policy extra-args refuse.

Extra arguments may only add behaviour, so only flags known to do that are taken. The board checks them as you type and the machine checks again at launch. These are the flags a machine can add:

CLI Flags
Claude Code --chrome, --no-chrome, --ide, --verbose, --ax-screen-reader, --brief, --debug [filter] (-d), --debug-file <path>, --effort <level>, --autocompact <size>, --name <name> (-n)
Codex --search, --no-alt-screen, --strict-config, --image <file> (-i)
Gemini CLI --debug (-d), --screen-reader

Any other flag is refused, including ones the CLI doesn’t list in its help: Andon sets permissions, settings, MCP, the session, the prompt and the model itself. A word after a flag is that flag’s value only when the flag takes one; otherwise it would be the prompt or one of the CLI’s commands (exec, mcp, plugin), and is refused. For Claude Code’s --debug, put the filter after = (--debug=mcp). The text is split into words the way a shell would, but nothing is expanded and it never goes through a shell. A run whose arguments break a rule fails with the reason.

Check it

  1. In Settings → Machines, the machine is online and lists the agents you installed.
  2. Run a card on a direct machine. The run heading ends in Terminal, and tmux -L andon ls on the machine lists andon-<run id>.
  3. Show in Terminal opens a window attached to the session. Reply from the board, and the reply shows up in it.