Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

One machine, several boards

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

A computer runs one Andon agent per board. To take work from a second board, add a second agent, called a profile, next to the first. Each has its own config, service, logs and updates.

Add a second board

  1. Run setup against the other board:

    shell
    andon setup --url https://<other board>
  2. Setup asks what to do:

    text
    This machine already runs an Andon agent for https://a.example.test (as "mac").
    1) Add a second agent for https://b.example.test and keep the one for https://a.example.test running
    2) Move this machine to https://b.example.test: the agent for https://a.example.test stops here
    3) Cancel: keep this machine on https://a.example.test only
    Choose 1, 2 or 3 [1]:
  3. Approve the machine on the other board.

Choice What happens
Add (the default) Enrolls a second agent as a profile named after the board’s host (b-example-test).
Move Waits for the new board to approve this machine (a denied or expired request changes nothing). Then it stops the first agent’s service and renames its config to config.<slug>.<time>.json, and a file credential to credentials.<slug>.<time>.json. Nothing is deleted. Revoke the old machine on the old board yourself.
Cancel Changes nothing.

Unattended setup doesn’t guess: with no terminal, pass --other-board add, move or keep. The installer takes the same flag. andon --profile <name> setup --url <board> enrolls a profile directly, without the question.

What a profile has of its own

What First agent A profile
Config ~/.config/andon/ ~/.config/andon/profiles/<name>/
Service on a Mac dev.andon.agent dev.andon.agent.<name>
Service on Linux andon-agent.service andon-agent-<name>.service
The agent itself ~/.local/share/andon/andon.mjs ~/.local/share/andon/profiles/<name>/andon.mjs
Hook and terminal ports the defaults (hooks on 7777) the first free pair from 7787 up

It also has its own state, logs and tmux socket. Each profile runs its own copy of the agent, so each updates from its own board.

Run a command against a profile

Commands go to the first agent unless you name a profile first:

shell
andon profiles # every agent on this machine
andon --profile b-example-test status
andon --profile b-example-test doctor

ANDON_PROFILE=<name> does the same.

Update a profile

andon update updates the first agent, then lists every other agent with its command (andon --profile <name> update).

Each profile pins its own release key. Get the second board’s key through a channel you trust and save it as ~/.local/share/andon/profiles/<name>/update-key.pub before you update it. With no key pinned there, andon --profile <name> update --trust-board installs that board’s build on its checksums alone, and when that board serves no build signed with Andon’s release key, the profile follows Andon’s official releases instead. See Agent updates.

The installer refuses to replace an existing install. Use andon update (with --profile for a profile) to repair one.

One machine per board

A board knows a computer by the id in ~/.config/andon/host-id, which every agent and profile on the computer shares. The same computer can’t be enrolled twice in one org: the approval page says it is already there as another machine and keeps Approve off, and an install code for it is refused (the code stays usable).

This usually means you reached the board by a second address, localhost and a Tailscale name say, and setup took it for another board. Use the existing machine, or revoke it in Settings → Machines and run setup again.

A computer enrolled twice in one org is marked Same computer in Settings → Machines. Revoke one, then stop its agent on the computer: andon profiles lists the agents, and andon --profile <name> uninstall-service stops one. See Remove a machine.

Limits

  • A new profile starts with a copy of the first agent’s build and must pin its own board’s key before signed updates.
  • Each agent picks its own Tailscale serve ports and leaves ports already served alone. If both agents open a preview at the same moment, they can pick the same port.