Register a Worker

A worker is a machine running Podman (or Docker) that executes DevBoxes on behalf of the orchestrator. Registration is a one-time step where the CLI selects a tenant and generates a worker identity.

Prerequisites

• CLI installed and authenticated (clustercode login)
• Podman (or Docker) installed and running on this machine
• Network access to the orchestrator (outbound only — no inbound ports needed)

Quick path

clustercode onboard

The onboard wizard checks everything (auth, tenant selection, orchestrator reachability, container runtime, disk/memory) and fixes issues automatically.

Manual path

Start the worker

clustercode worker

On first run, the CLI:

1. Checks your authentication
2. Fetches available tenants from the orchestrator
3. Lets you pick a tenant (or auto-selects if there’s only one)
4. Saves your selection
5. Starts the worker

On subsequent runs, it reuses your saved selection and starts immediately.

To pick a container engine explicitly, pass --podman or --docker. Otherwise the worker uses whichever supported engine it finds.

Verify

clustercode status

You should see:

  User:          you@example.com
  Worker:        a1b2c3d4
  Tenant:        your-tenant
  Orchestrator:  console.clustercode.io
  Connection:    Connected

The worker also appears in the orchestrator dashboard under the Workers panel.

Health check

Run clustercode doctor at any time to verify the worker’s health:

clustercode doctor

It checks: authentication, worker registration, worker binary, orchestrator connectivity, WSL2 (Windows only), container runtime (Podman/Docker), disk space, and available memory.

Multi-machine setup

Repeat these steps on each machine you want to connect. Workers connect outbound — no inbound ports needed, works behind NAT and firewalls.

Next steps

• Agent sign-in — do this next. Registering the worker prepares the machine; it does not sign your agents in or store your service access tokens. Without both, your first DevBox launches fine and the first agent command fails on auth. Once per worker, not once per DevBox.
• Quickstart — launch your first DevBox
• Self-hosting: Requirements — hardware and network requirements
• Self-hosting: Worker Agent — how the worker connects and stays online