Worker Agent

The worker agent is a lightweight Go binary that runs on each machine and bridges the orchestrator to local Podman (or Docker) DevBoxes. It requires no runtime dependencies — just download and run.

Architecture

Orchestrator (cloud)
    ▲
    │  WebSocket (outbound from worker)
    │
Worker Agent (your machine)
    │
    │  child_process / Podman API
    │
    ▼
Podman containers

Lifecycle

1. Connects to the orchestrator via WebSocket (outbound, authenticated with worker token)
2. Registers itself with system info (see below)
3. Sends heartbeats every 10 seconds (see below)
4. Receives commands from the orchestrator
5. Executes DevBox operations locally via Podman or Docker

Registration

On connect, the agent sends a worker.register message with:

Field	Type	Description
name	string	Worker name (env, config, or hostname)
hostname	string	System hostname
platform	string	OS — linux, darwin, or windows
cpuCount	int	Number of CPU cores
memoryTotal	uint64	Total RAM in bytes
containerEngines	string[]	Detected engines (podman, docker)
agentVersion	string	Agent version, e.g. 2.0.0
mode	string	byom (bring-your-own-machine) or fleet

Heartbeat

Every 10 seconds the agent sends a worker.heartbeat with:

Field	Type	Description
cpuUsage	float64	CPU usage 0–100%
memoryFree	uint64	Free RAM in bytes
diskTotal	uint64?	Total disk in bytes
diskFree	uint64?	Free disk in bytes
containersRunning	int	Number of running DevBoxes
gatewayStatus	string?	Gateway connectivity status
gatewayStatusDetail	string?	Additional gateway info

Commands

Command	Action
DevBox.create	Create a new DevBox from image
DevBox.setup	Run initial setup (clone repo, generate CLAUDE.md)
DevBox.start	Start a stopped DevBox
DevBox.stop	Stop a running DevBox
DevBox.remove	Remove a DevBox
DevBox.list	List DevBoxes for a tenant
DevBox.list-all	List all DevBoxes across tenants
DevBox.exec	Execute a command inside a DevBox
DevBox.exec.background	Run a background command in a DevBox
DevBox.exec.background.kill	Kill a background command
DevBox.exec.background.capture	Capture background command output
images.list	List available DevBox images
image.check	Check if an image exists
image.delete	Delete a DevBox image
image.build	Build a DevBox image from Dockerfile
terminal.open	Start an interactive shell session
terminal.input	Forward keystrokes to a terminal
terminal.resize	Resize terminal dimensions
terminal.close	Close a terminal session
display.open	Open a VNC display session
display.close	Close a VNC display session

Terminal Streaming

Terminal output from DevBoxes is streamed back through the worker agent to the orchestrator, which relays it to the browser via WebSocket. This gives you a live web terminal with full xterm.js rendering.

Reconnection

If the WebSocket connection drops, the agent reconnects automatically with exponential backoff:

1s → 2s → 4s → 8s → 16s → 30s (max)

DevBoxes continue running during disconnection — they’re not affected by the agent’s connection state.

Configuration

The worker agent reads configuration from environment variables, YAML config files, or CLI flags.

BYOM mode (bring-your-own-machine — default):

Path	Contents
~/.clustercode/credentials.json	Auth token from clustercode login
~/.clustercode/worker.json	Worker registration state
~/.clustercode/config.json	User preferences (WORKER_NAME)

Fleet mode (managed deployments):

Path	Contents
/etc/clustercode/agent.yaml	Full agent config (URL, token, mode, security)
AGENT_CONFIG env var	Override the YAML path

Key environment variables: ORCHESTRATOR_WS_URL, WORKER_NAME, AGENT_MODE, PODMAN_PATH, DATA_DIR, SECURITY_FLOOR. See Environment Variables for the full list.

Process Management

The worker agent runs as a foreground process. To run it as a background service:

Linux (systemd):

clustercode worker

macOS (launchd):

clustercode worker

The agent is designed to be restarted safely — it picks up existing DevBoxes on reconnection.