Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

Linux 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 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

  1. Run the installer from your board:

    shell
    curl -fsSL https://<your board>/install.sh | sh
  2. Say yes when the installer offers to install git, tmux, curl or gh with apt-get, dnf or pacman. It says when it uses sudo.

  3. It needs Node 22 or newer. On Fedora and Arch it offers the distro’s nodejs package. On Debian and Ubuntu, whose nodejs is older, install Node 22 yourself with fnm (no root) or NodeSource, then run the installer again. It never pipes a script into sudo for you.

  4. Approve the machine. With a display it opens your browser. Without one (a server, an SSH session) it prints an /enroll link 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.

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

  7. The installer ends with andon doctor. Fix anything marked ✗ and run andon doctor again.

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

shell
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

shell
andon doctor

On 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