clustercode worker
clustercode worker# or, the same command under another name:clustercode connectDescription
Section titled “Description”The worker command selects a tenant (if needed) and starts the worker on this machine.
clustercode connect is an alias of clustercode worker: it takes the same options and behaves identically, so use whichever name you prefer.
On first run, it walks you through setup:
- Checks that you’re logged in (prompts to run
clustercode loginif not) - Fetches the tenants your account can access
- If you have more than one, lets you pick which to join
- Starts the worker
On later runs, it reuses your saved selection and starts immediately.
Options
Section titled “Options”| Flag | Description |
|---|---|
--podman | Use Podman as the container engine |
--docker | Use Docker as the container engine |
--prerelease | Use the latest prerelease worker agent |
--agent-version <version> | Pin an exact worker agent version (e.g. 1.0.0-alpha.4) |
-v, --verbose | Verbose worker agent logging |
--doctor | Run clustercode doctor first, then connect |
If you don’t pass either engine flag, the worker uses whichever supported engine it finds on the machine. Pass one — not both — to force the choice.
Check and fix, then connect
Section titled “Check and fix, then connect”Add --doctor to run the health checks on the way in:
clustercode connect --doctorThis runs the full clustercode doctor flow first — including its offer to run clustercode onboard when a check fails — and connects the worker once doctor has finished. It’s the quickest way to fix setup issues and get online in one step.
- Issues left unresolved — you declined the fix, the fix didn’t clear them, or there’s no terminal to ask — produce a warning, and the worker connects anyway. The worker still enforces its hard prerequisites itself (being logged in, having a tenant, having a container engine), with the same errors as without
--doctor. - Cancelling a doctor prompt (
Ctrl+CorEsc) stops without connecting. - Invalid flags, such as
--podman --dockertogether, are rejected straight away, before doctor runs.
--doctor works the same on clustercode worker --doctor.
Connection
Section titled “Connection”The worker connects outbound to the orchestrator — no inbound ports, no firewall rules, works behind NAT. If the connection drops, it reconnects automatically.
Leave the command running to keep the worker online; stop it with Ctrl+C.
Verify
Section titled “Verify”clustercode statusYour worker also appears in the dashboard under the Workers panel.