# 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](https://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](https://andon-docs.pages.dev/machines/orca-or-direct.md)).

## Install

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

   ```sh
   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](https://andon-docs.pages.dev/machines/orca-or-direct.md#presets)). 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`:

```sh
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](https://andon-docs.pages.dev/machines/updates.md)). |
| `--other-board add\|move\|keep` | This Mac already runs an agent for another board ([One machine, several boards](https://andon-docs.pages.dev/machines/multiple-agents.md)). |
| `--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](https://andon-docs.pages.dev/machines/files-on-a-machine.md) lists every file, which config folder `andon` reads, and which one wins.

Read the log as it is written:

```sh
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](https://andon-docs.pages.dev/machines/remove-a-machine.md).

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

```sh
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](https://andon-docs.pages.dev/machines/orca-or-direct.md#show-in-terminal).

## Next

- [Several CLI accounts and model providers](https://andon-docs.pages.dev/machines/accounts-and-providers.md)
- [Agent updates](https://andon-docs.pages.dev/machines/updates.md)
- [The `use-andon` skill](https://andon-docs.pages.dev/machines/use-andon-skill.md), which the agent installs for your coding agents
