Linux machines
Put the Andon agent on a Linux desktop or server (Debian, Ubuntu, Fedora or Arch; x64 or arm64) so it can run cards from your board. The machine is yours: it runs your cards, not other people’s. The agent runs as a systemd user service. On a server, turn on linger so it keeps running when nobody is logged in.
For a NAS, see A NAS as a machine. For Windows, run this Linux agent in WSL2: Windows machines.
Install
-
Run the installer from your board:
shell curl -fsSL https://<your board>/install.sh | sh -
Say yes when the installer offers to install git, tmux, curl or gh with
apt-get,dnforpacman. It says when it usessudo. -
It needs Node 22 or newer. On Fedora and Arch it offers the distro’s
nodejspackage. On Debian and Ubuntu, whosenodejsis older, install Node 22 yourself with fnm (no root) or NodeSource, then run the installer again. It never pipes a script intosudofor you. -
Approve the machine. With a display it opens your browser. Without one (a server, an SSH session) it prints an
/enrolllink and a code: open the link on your phone, check that the code matches, and approve. Once approved, the page tells you to go back to the terminal: 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.
-
Answer Keep the agent running when you’re logged out? (linger,
loginctl enable-linger): yes on a server, no on a desktop you stay logged in to. Enter is yes. -
The installer ends with
andon doctor. Fix anything marked ✗ and runandon doctoragain.
The installer never installs ffmpeg. Without it, image and video previews are off on this machine. Install it later and they turn on at the next sync.
Linux has no Claude app for setup to find, so it doesn’t offer Claude Code on its own. Pass --install-claude to
install it (Anthropic’s installer, into ~/.local/bin) and sign it in. To use Gemini CLI, install it yourself
(npm install -g @google/gemini-cli) and sign it in through Andon:
Gemini CLI sign-in.
Without Orca, the machine runs in direct mode: git worktrees and the coding agent in the agent’s own tmux. See Orca or direct.
Unattended installs
With no terminal to ask on, the installer changes nothing it would have asked about. Pass flags after sh -s --:
curl -fsSL https://<your board>/install.sh | sh -s -- --yes --code <install code> --preset standard| Flag | What it does |
|---|---|
--yes |
Answers every question with its default: package installs, and linger on a server. It never installs Claude Code. |
--code <install code> |
Enrolls with an install code from the board instead of an approval. |
--preset locked|standard|open |
Picks the policy preset. 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 machine already runs an agent for another board (One machine, several boards). |
--no-service |
Enrolls without installing the service. |
--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. |
The installer has no linger flag. To set linger yourself, run andon install-service --linger (or --no-linger) once
the agent is installed.
The service
| To | Run |
|---|---|
| install and start the service, and set linger | andon install-service [--linger | --no-linger] |
| stop and disable the service | andon uninstall-service |
| read its log | journalctl --user -u andon-agent.service |
| restart it | systemctl --user restart andon-agent.service |
| see the machine, board and version | andon status |
andon install-service writes the unit, enables it and starts it. It doesn’t restart an agent that is already running: use systemctl --user restart for that. With neither flag it asks about linger when linger
is off; with --yes it takes the default (on without a display).
andon uninstall-service leaves the unit file in ~/.config/systemd/user. To take the agent off the machine for good,
see Remove a machine.
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 Secret Service (secret-tool) on a desktop with a session bus, else ~/.config/andon/credentials.json (readable only by you) |
| Service | ~/.config/systemd/user/andon-agent.service |
| Run state, accounts and Gemini homes | ~/.local/state/andon/ |
| Card worktrees in direct mode | ~/Projects/worktrees/<repo>/<branch> |
| Scratch folders it removes | your Trash: gio trash when it is installed, else ~/.local/share/Trash |
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.
Check it
andon doctorOn Linux, andon doctor also checks:
- the user session bus
- the Secret Service, when it holds the credential
- linger
- whether there is a display
- that the Trash folder is writable
Each fix is printed for your distro (sudo apt install …, sudo dnf install …, sudo pacman -S …).
After a reboot, look for the machine on the board before you rely on it. If it stays offline until you log in over SSH, linger isn’t starting your user’s services at boot on that system.
Next
- Several CLI accounts and model providers
- Agent updates, including the board terminal’s helper
- The
use-andonskill, which the agent installs for your coding agents
