# 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](https://andon-docs.pages.dev/machines/nas.md). For Windows, run this Linux agent in WSL2: [Windows machines](https://andon-docs.pages.dev/machines/windows.md).

## Install

1. Run the installer from your board:

   ```sh
   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](https://github.com/Schniz/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](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. 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](https://andon-docs.pages.dev/machines/accounts-and-providers.md#sign-in-to-gemini-cli).

Without Orca, the machine runs in direct mode: git worktrees and the coding agent in the agent's own tmux. See
[Orca or direct](https://andon-docs.pages.dev/machines/orca-or-direct.md).

### Unattended installs

With no terminal to ask on, the installer changes nothing it would have asked about. Pass flags after `sh -s --`:

```sh
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](https://andon-docs.pages.dev/machines/updates.md)). |
| `--other-board add\|move\|keep` | This machine 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 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](https://andon-docs.pages.dev/machines/remove-a-machine.md).

## 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](https://andon-docs.pages.dev/machines/files-on-a-machine.md) lists every file, which config folder `andon` reads, and which one wins.

## Check it

```sh
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

- [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), including the board terminal's helper
- [The `use-andon` skill](https://andon-docs.pages.dev/machines/use-andon-skill.md), which the agent installs for your coding agents
