Worker Agent

The worker agent is a lightweight Go binary that runs on each machine and bridges the orchestrator to local Podman (or Docker) containers. 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 container 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 containers
gatewayStatus	string?	Gateway connectivity status
gatewayStatusDetail	string?	Additional gateway info

Commands

Command	Action
container.create	Create a new container from image
container.setup	Run initial setup (clone repo, generate CLAUDE.md)
container.start	Start a stopped container
container.stop	Stop a running container
container.remove	Remove a container
container.list	List containers for a tenant
container.list-all	List all containers across tenants
container.exec	Execute a command inside a container
container.exec.background	Run a background command in a container
container.exec.background.kill	Kill a background command
container.exec.background.capture	Capture background command output
images.list	List available container images
image.check	Check if an image exists
image.delete	Delete a container image
image.build	Build a container 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 containers 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)

Containers 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
~/.cropscode/credentials.json	Auth token from cropscode login
~/.cropscode/worker.json	Worker registration state
~/.cropscode/config.json	User preferences (WORKER_NAME)

Fleet mode (managed deployments):

Path	Contents
/etc/cropscode/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):

cropscode worker

macOS (launchd):

cropscode worker

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