AI Agents

Use Spunto workers as isolated sandboxes for AI coding agents — full API control, zero setup overhead.

Spunto workers are ideal environments for AI coding agents. Each worker is an isolated Docker container with a full development stack — code execution, git, terminal access — exposed via a clean REST API.

Isolation — each agent run gets a fresh, contained environment; no host system access
Pre-configured — repos are cloned, credentials are set, tools are installed at spawn
Ephemeral — delete the worker when done; no cleanup needed
API-driven — spawn, interact, read output, and destroy entirely via HTTP

1. POST /api/orgs/{orgId}/projects/{projectId}/workers   → spawn worker
2. Poll GET /api/orgs/{orgId}/projects/{projectId}/workers/{workerId}  → wait for "ready"
3. Use the worker (terminal, git, file system via code-server)
4. DELETE /api/orgs/{orgId}/projects/{projectId}/workers/{workerId}   → destroy

Create an API key scoped to the org the agent should operate in — from Account Settings, pick workers:read + workers:write at minimum (add workers:exec if the agent needs an interactive terminal, and projects:read/projects:write if it also manages projects). For an agent deployed long-term outside any one person's account, create an org-owned (service account) key instead of a personal one — it keeps working if the creator leaves the org.

curl -H "Authorization: Bearer spk_..." \
  https://spunto.net/api/orgs/{orgId}/projects

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  https://spunto.net/api/orgs/{orgId}/projects/{projectId}/workers

Response:

{
  "id": "wkr_abc123",
  "state": "spawning",
  "setupStatus": { "phase": "initializing", ... }
}

Poll the worker endpoint every 2 seconds until state === "ready":

curl -H "Authorization: Bearer <token>" \
  https://spunto.net/api/orgs/{orgId}/projects/{projectId}/workers/wkr_abc123

The setupStatus.phase field tracks each step: cloning → features → lifecycle → ready.

Use the WebSocket terminal endpoint to execute commands in the worker:

wss://spunto.net/api/workers/{workerId}/terminal?mode=terminal

Protocol:

Send { "type": "input", "data": "<base64-encoded command>" }
Receive { "type": "output", "data": "<base64-encoded output>" }

This gives you a full PTY inside the container.

curl -H "Authorization: Bearer <token>" \
  "https://spunto.net/api/orgs/{orgId}/projects/{projectId}/workers/{workerId}/logs?tail=100"

Returns plain text stdout/stderr from the container.

Use User Secrets to inject credentials (API keys, tokens) as environment variables into every worker, without storing them in the project config:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ANTHROPIC_API_KEY", "value": "sk-ant-..." }' \
  https://spunto.net/api/users/me/secrets

The secret is encrypted at rest and injected at spawn time. Values are never returned by the API.

A minimal setup for running Claude Code in an isolated Spunto worker:

Create a project with your codebase repo and ANTHROPIC_API_KEY in User Secrets
Set postCreateCommand: "npm install -g @anthropic-ai/claude-code"
Spawn a worker via API
Wait for state === "ready"
Connect via WebSocket terminal and run claude "implement feature X"
Read output, commit changes, delete worker

Tip

Workers have GITHUB_TOKEN pre-injected. Claude Code (and gh CLI) will pick it up automatically for PR creation, issue reading, etc.

After an agent run, check what changed:

curl -H "Authorization: Bearer <token>" \
  https://spunto.net/api/orgs/{orgId}/projects/{projectId}/workers/{workerId}/git-status

Returns per-repo branch and modified file count — useful for CI pipelines that spawn a worker, run an agent, and then open a PR.

PreviousAdding a Node NextAPI Reference