Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

Mac machines

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

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.app but no claude, 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

  1. In Terminal, run the installer from your board:

    shell
    curl -fsSL https://<your board>/install.sh | sh
  2. Answer Install with Homebrew? if something is missing. Node 22 comes from Homebrew’s node@22, which stays keg-only: your default node isn’t relinked, and the agent uses the keg’s path.

  3. 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. Type s to skip and run in direct mode.

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

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

  6. The installer ends with andon doctor. Fix anything it marks ✗ and run andon doctor again.

If the installer warns that ~/.local/bin isn’t on your PATH, add it to ~/.zprofile:

shell
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:

shell
tail -f ~/Library/Logs/andon/agent.log

The 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:

shell
andon policy terminal-app iTerm
andon policy auto-open-terminal on # open that window by itself as each interactive run starts

More on runs in a terminal: Orca or direct.

Next