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. You can opt to push the new key to any currently connected workers so they reconnect seamlessly; offline workers must be updated with the new --token before they can reconnect. The push is sent as a token_rotated worker command and only reaches workers that are online at the moment of rotation — see API license rotation.

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.