Mac machines
Put the Andon agent on a Mac so it can run cards from your board. The machine is yours: it runs your cards, not other people’s. It runs as a LaunchAgent under your user and starts each time you log in.
Before you start
- Homebrew (brew.sh). The installer uses it for anything missing: git, tmux, gh, curl and Node 22. Without Homebrew it lists what is missing: install those yourself, then run the installer again.
- A coding agent CLI: Claude Code, Codex or Gemini CLI. The Claude desktop app alone isn’t enough, because Andon runs
Claude through Claude Code, the CLI. If the installer finds
Claude.appbut noclaude, setup offers to install Claude Code and sign it in. - Orca is optional. Without it the machine runs in direct mode (Orca or direct).
Install
-
In Terminal, run the installer from your board:
shell curl -fsSL https://<your board>/install.sh | sh -
Answer Install with Homebrew? if something is missing. Node 22 comes from Homebrew’s
node@22, which stays keg-only: your defaultnodeisn’t relinked, and the agent uses the keg’s path. -
If Orca is installed but its CLI isn’t on your
PATH, the installer pauses. Turn the CLI on in Orca under Settings → Experimental → CLI, then press Enter. Typesto skip and run in direct mode. -
Approve the machine in the browser tab that opens. Check that the code on the page matches the one in Terminal. Once approved, the page tells you to go back to Terminal, which rings its bell: setup waits there for your answers.
-
Pick a policy preset: Locked, Standard or Open (what each allows). Enter picks Open, which never stops a run for a recipe change, but runs a recipe an admin adds or edits on the board without your approval. Pick Standard to approve each change on this machine first. Setup then lists the folders it will search for repositories; for each one outside the workspace roots it asks first, and Enter adds it.
-
The installer ends with
andon doctor. Fix anything it marks ✗ and runandon doctoragain.
If the installer warns that ~/.local/bin isn’t on your PATH, add it to ~/.zprofile:
export PATH="$HOME/.local/bin:$PATH"The installer never installs ffmpeg. Without it, image and video previews are off on this machine. Install it later
(brew install ffmpeg) and they turn on at the next sync.
Installer flags
Pass flags after sh -s --, for example curl -fsSL https://<your board>/install.sh | sh -s -- --yes --preset standard.
| Flag | What it does |
|---|---|
--yes |
Answers every question with its default, Homebrew installs included. It never installs Claude Code. |
--code <install code> |
Enrolls with an install code from the board instead of a browser approval. |
--preset locked|standard|open |
Picks the policy preset without asking. With --yes and no preset, the machine gets Open. |
--install-claude, --no-install-claude |
Installs Claude Code, or skips the question. |
--update-key <key> |
Pins another release key for self-updates than the one the installer names: your board’s own, else Andon’s (Agent updates). |
--other-board add|move|keep |
This Mac already runs an agent for another board (One machine, several boards). |
--no-service |
Enrolls without installing the LaunchAgent. |
--no-browser |
Prints the approval link and code instead of opening a browser. |
--trust-org, --approve-current |
Adjusts the preset’s recipe approval after it is applied. |
--url <board> |
The board to enroll with, when the installer doesn’t know it. |
Where things are
| What | Where |
|---|---|
The andon command |
~/.local/bin/andon |
| The agent itself | ~/.local/share/andon/andon.mjs |
| Config | ~/.config/andon/config.json (readable only by you) |
| Machine credential | the login Keychain, as a generic password for the service andon-agent |
| Service | ~/Library/LaunchAgents/dev.andon.agent.plist |
| Logs | ~/Library/Logs/andon/agent.log and agent.err.log |
| Run state, accounts and Gemini homes | ~/.local/state/andon/ |
| Card worktrees in direct mode | ~/Projects/worktrees/<repo>/<branch> |
| Scratch folders it removes | your Trash (~/.Trash), never deleted outright |
These are the installer’s paths. With the desktop app, or with ANDON_CONFIG_DIR set, the config is elsewhere:
Files on a machine lists every file, which config folder andon reads, and which one wins.
Read the log as it is written:
tail -f ~/Library/Logs/andon/agent.logThe service
The LaunchAgent starts the agent when you log in and starts it again if it stops. It runs only while you are logged in to the Mac: on a Mac that should take work around the clock, keep a user logged in and turn off sleep.
| To | Run |
|---|---|
| install or restart the service | andon install-service |
| stop it and take it out of launchd | andon uninstall-service |
| see the machine, board and version | andon status |
| check everything the agent needs | andon doctor |
andon uninstall-service leaves the plist file in ~/Library/LaunchAgents. To take the agent off the Mac for good, see
Remove a machine.
Show in Terminal
On a Mac, a run’s Show in Terminal opens a window attached to the run’s session. It opens in Terminal unless you pick another app:
andon policy terminal-app iTermandon policy auto-open-terminal on # open that window by itself as each interactive run startsMore on runs in a terminal: Orca or direct.
Next
- Several CLI accounts and model providers
- Agent updates
- The
use-andonskill, which the agent installs for your coding agents
