worker setup

overview#

each machine that will execute tasks needs the overlord worker package installed. workers connect to the server via websocket, receive task assignments, manage git workspaces, and run ai agents in pty terminals.

installation#

on each worker machine:

npm install -g @overlordai/cli @overlordai/worker

interactive setup#

run the setup wizard:

overlord setup worker

the wizard prompts for:

  1. server url — the overlord server address (e.g., https://overlord.yourdomain.com or http://localhost:9000)
  2. registration token — a one-time token generated in admin → settings → tokens
  3. machine name — a display name for this worker
  4. max slots — maximum number of concurrent tasks (default: 2)

the wizard writes configuration to ~/.overlord-worker/.env and starts the worker service.

info

each worker needs its own unique registration token. generate one per machine in admin → settings → tokens (web dashboard).

web ui guided setup#

alternatively, open https://your-server/machines/setup in a browser. the page provides step-by-step instructions with the exact commands to run on the worker machine.

what the worker does#

once running, the worker:

  • connects to the server via websocket (auto-reconnects on failure)
  • registers with the one-time token on first run, then uses jwt for subsequent connections
  • sends heartbeats every 30 seconds with cpu, memory, and disk usage
  • reports installed agent capabilities (claude, cursor, codex)
  • receives task assignments and creates isolated git worktrees
  • spawns pty terminals running the configured ai agent
  • streams terminal output back to the server in real time
  • manages cursor remote tunnels for workspace access

configuration#

worker configuration is stored in ~/.overlord-worker/.env:

variabledefaultdescription
OVERLORD_HOST—server url (required)
OVERLORD_WORKER_TOKEN—one-time registration token
OVERLORD_MACHINE_NAMEhostnamedisplay name
OVERLORD_WORKSPACE_ROOT~/.overlord-worker/workspacestask workspace directory
OVERLORD_MAX_SLOTS2max concurrent tasks
OVERLORD_DATA_DIR~/.overlord-workerconfig and jwt storage
OVERLORD_SSH_KEY_PATH—ssh key for git operations

non-interactive mode#

for automation or ci, pass --server and --token as cli flags. non-interactive mode activates automatically when both are provided:

overlord setup worker \
  --server https://overlord.yourdomain.com \
  --token ovw_1_abc123 \
  --name worker-01 \
  --slots 4

verify#

after setup, check the machines page in the web dashboard — the new worker should appear with status "online". you can also verify from the cli:

ov machine list

next steps#

installationdeployment guide