automaintainer/ docs
Dashboard →

Add a worker

Runs execute on a worker — a machine you control that has the AI harnesses installed and your provider key configured. You can connect one or many; AM routes work across the fleet.

Install

On the worker host, run the command from the Workers tab:

am-cloud worker install \
  --panel wss://automaintainer.intrane.fr/ws/worker \
  --token <your-license-key>

This installs a service that connects to the panel over WebSocket. The worker appears in the Workers tab within ~15s.

User service vs system service

# user service (no sudo) — default
am-cloud worker install --panel <url> --token <key>

# system‑wide (needs root)
sudo am-cloud worker install --panel <url> --token <key> --system

For a user service to keep running after you log out, enable linger:

sudo loginctl enable-linger "$USER"

What a worker needs

  • An AI harness: claude, opencode, pi, or tau.
  • git, gh (for PRs), and the a2a / a2a-spawn bus tools.
  • A working provider key for at least one harness (BYOK).
  • (optional) tokscale on PATH to report per‑run token/cost in the panel — see Run costs.

The Workers tab shows a checklist of these per worker, plus live RAM/CPU and a readiness badge. See Worker & fleet health.

Gotcha — running as root. Some harnesses refuse to bypass approval prompts as root. AM handles this automatically (it sets IS_SANDBOX=1 for claude), but if you see a permissions error in a run, see Worker not ready.

Verify it's actually ready

Installed ≠ working. A harness with no provider key (or an empty balance) will accept a run and silently do nothing. Always confirm with the Test button — see Verify readiness.

Rotating the license key

If you ever need to invalidate an exposed or stale license key, open the Settings tab and click Regenerate key. The dashboard has an Also update connected workers checkbox next to the button. When checked, the panel pushes the new key over each connected worker's live WebSocket as a token_rotated command, so they reconnect seamlessly. The checkbox state is saved in browser localStorage as am-regen-notify_workers (1 for checked, 0 for unchecked), so it is restored the next time you open Settings.

Offline workers, or workers whose send buffers are full at the moment of rotation, do not receive the push and must be updated with the new --token before they can reconnect. See API license rotation for the programmatic equivalent and the accepted notify_workers values.

Removing a worker

Stop and disable the service on the host:

am-cloud worker uninstall   # or: systemctl --user disable --now am-cloud-worker

You can also disable a worker from the Workers tab without uninstalling.