SpuntoSpunto/Docs

Adding a Node

Connect a server to your organization and have it accept workers and deployments in minutes.

This is what you do today to get a working node: create it in the dashboard, run one Docker command on your server, and it's online. There's no extra configuration step — every node behaves the same way regardless of where it's hosted.

  • Docker installed and running on the server
  • Outbound HTTPS/WSS access to spunto.net (no inbound ports needed)
  • /var/run/docker.sock accessible to the agent container

1

Create a node in the dashboard

Go to Dashboard → [Your Org] → Nodes → New node.

Give it a name (e.g. prod-eu-1) and click Create. Copy the NODE_TOKEN shown — it's only displayed once.

2

Deploy the agent on your server

SSH into your server and run:

docker run -d \
  --name spunto-agent \
  --restart unless-stopped \
  -e NODE_TOKEN=your_token_here \
  -e API_URL=https://spunto.net \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/coderhammer/spunto-agent:latest

The agent connects within a few seconds — outbound only, nothing to open on your firewall.

3

Verify the node is online

Back in the dashboard, the node's status should switch to online. If it stays offline after 30 seconds, check the agent logs:

docker logs spunto-agent -f
4

Spawn a worker

Go to a project and click New worker. Spunto automatically schedules it on the new node (least-loaded selection across all online nodes in the org).

If you don't want to manage a server yourself, Spunto can provision one for you:

  1. Connect your GCP account from Account Settings (OAuth, cloud-platform scope)
  2. Nodes → Add node → Google Cloud
  3. Select region, machine type, and disk size
  4. Click Create

Spunto calls the Compute Engine API to create a Debian VM with a startup script that installs Docker and runs the agent automatically — no manual docker run needed. The VM provisions in about 2 minutes and the node goes online by itself.

Note

The GCP refresh token is stored encrypted and only used to call the Compute Engine API on your behalf when provisioning or removing a node.

You can register multiple nodes under the same organization. Workers and deployment services are scheduled on the least-loaded online node — the one with the fewest running workers.

If no node is online when a worker is created, the creation fails with a clear error rather than silently queuing.

Before shutting down a server:

  1. Go to the node's detail page
  2. Click Drain — the node stops accepting new workers
  3. Wait for existing workers to finish, or stop/move them manually
  4. Shut down the server

When the agent reconnects (after a restart), the node resumes accepting workers automatically — draining is not persisted across reconnects unless you drain it again.

If a token is compromised:

  1. Go to Nodes → select the node → Rotate token
  2. A new token is generated; the old one is invalidated immediately
  3. Update the NODE_TOKEN env var on your server and restart the agent container

Warning

The NODE_TOKEN gives full control over the node. Keep it secret. It's stored encrypted in the database and is only shown once, at creation time.

  • The agent only accepts commands from the API WebSocket connection it initiated — nothing listens for inbound connections on the node
  • Worker containers run as isolated Docker containers with no host network access
  • The Docker socket is mounted read-write — the agent needs it to manage containers. Treat any machine you connect as a node as trusted infrastructure for your organization
PreviousOverviewNextAI Agents