SpuntoSpunto/Docs

Worker Nodes

Worker nodes are compute servers running the Spunto agent — your infrastructure, fully under your control.

A worker node is a compute server registered with an organization. The Spunto agent runs on it, connects outbound to the API via WebSocket, and executes Docker commands to spawn and manage worker containers.

This architecture — called BYOC (Bring Your Own Compute) — means:

  • No inbound ports required — the agent connects outbound, so no firewall changes are needed
  • Your infrastructure — use any server: cloud VM, on-premise machine, Raspberry Pi
  • Full isolation — workers run as isolated Docker containers on the node's Docker engine
  • Multi-node support — add multiple nodes; new workers are scheduled on the least-loaded available node

Note

A node always belongs to a single organization. Every worker spawned by that organization runs on one of its nodes — there is no shared/multi-tenant fallback node.

[Your server]
  └── docker run ghcr.io/coderhammer/spunto-agent:latest
        ├── Connects to wss://your-api/api/agent/connect?token=...
        ├── Node status → online
        └── Receives spawn/stop/remove commands over WebSocket

The agent never exposes any port. All communication is initiated by the agent — it polls the API over the persistent WebSocket connection and reacts to the commands it receives (spawn, stop, remove, exec, tunnel open/close).

StatusDescription
onlineAgent connected, ready to accept workers
offlineAgent disconnected (network issue, stopped)
drainingAccepting no new workers (existing workers continue)

Workers never have ports published to the host. The agent connects itself to a container's network on demand and reaches it directly by its internal bridge IP — no host port mapping is needed.

  • Per-worker network isolation — every newly created worker gets its own dedicated Docker bridge network. Workers on the same node, even within the same organization, cannot reach each other's containers directly: all access goes through the proxy, which is the only place ownership and session are checked.
  • No ports published to the host — containers are fully isolated from the host network.
  • Deployments are isolated the same way — each deployment's services share a private network scoped to that deployment only (mp-dep-{deploymentId}), unreachable from workers or other deployments.

Note

Network isolation is applied when a worker's container is created. A worker that was provisioned before this isolation was rolled out keeps its existing network across a simple stop/start, and is migrated automatically the next time it's rebuilt.

Tip

This design means you can run the agent on a server with a strict firewall. Only outbound HTTPS/WSS to the API is required — nothing needs to be opened inbound.

Ready to connect a server? See Adding a Node for the step-by-step setup.

PreviousObservabilityNextAdding a Node