Sandboxes for agents.

Overview

The primary consumer of spawnd is a machine — an agent or app driving sandboxes at scale, not a human clicking around. A sandbox is one Firecracker microVM running a generic Ubuntu rootfs with common toolchains preinstalled (Node, Python, Go, Rust, and the usual build utilities). Guest code is hostile by default and isolated by construction; it cannot reach the host, the control plane, or another sandbox.

Quickstart

From zero to a running sandbox with curl. Base URL is https://spawnd.oonamy.xyz.

1. Request a magic link

   In dev mode the sign-in link is returned inline as devLink.

   Copy

   curl -s -X POST https://spawnd.oonamy.xyz/auth/magic-link \
     -H 'Content-Type: application/json' \
     -d '{"email":"you@example.com"}'
   # → { "sent": true, "expiresInMinutes": 15, "devLink": "https://spawnd.oonamy.xyz/auth/verify?token=..." }

2. Verify to get a session JWT

   Copy

   curl -s 'https://spawnd.oonamy.xyz/auth/verify?token=THE_TOKEN'
   # → { "token": "<jwt>", "user": {...}, "org": {...} }

3. Mint an org API key

   Session-authed. The full key is shown once — store it.

   Copy

   curl -s -X POST https://spawnd.oonamy.xyz/v1/keys \
     -H 'Authorization: Bearer <jwt>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"cli"}'
   # → { "key": "sk_live_...", "keyRecord": { "prefix": "sk_live_...", ... } }

4. Create a sandbox and exec

   Copy

   curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes \
     -H 'Authorization: Bearer sk_live_...' \
     -H 'Content-Type: application/json' -d '{"template":"base"}'
   # → { "id": "sbx_123", "state": "running", ... }
   
   curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/exec \
     -H 'Authorization: Bearer sk_live_...' \
     -H 'Content-Type: application/json' \
     -d '{"cmd":"echo","args":["hello from the box"]}'
   # → { "exitCode": 0, "stdout": "hello from the box\n", "durationMs": 42 }

5. Kill it when done

   Idempotent — billing stops the moment the VM is reaped.

   Copy

   curl -s -X DELETE https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123 \
     -H 'Authorization: Bearer sk_live_...'
   # → { "ok": true }

Authentication

Two disjoint auth surfaces share one port. A session JWT cannot drive the sandbox SDK, and an API key cannot manage keys.

Authorization: Bearer sk_live_...

Authorization: Bearer <jwt>

Sandboxes & sizes

template accepts a named size preset. Allocation (vCPU + memory) is fixed at create time and is the basis for resource-seconds billing. Unknown names fall back to the base size.

Lifecycle

Every sandbox supports the full lifecycle, and every verb is idempotent: kill on a dead sandbox succeeds, pause on a paused VM is a no-op, and create with the same idempotency key returns the same sandbox.

Legal states: creating, running, paused, stopping, stopped, killed, plus transient snapshotting and forking. killed is terminal. Cold starts use snapshot-restore from a warm pool, so create and resume are sub-second.

                 create
   (none) ─────────────────▶ creating
                                 │ boot + guest ping ok
                                 ▼
     ┌──────────── pause ◀── running ──▶ stopping ──▶ stopped
     │                        ▲   │        (graceful)      │
   paused ── resume ──────────┘   │ snapshot               │ resume/start
     │                            ▼                        │
     │                     (snapshot taken, stays running) │
     └──────────────── kill ─────┴──────── kill ───────────┘ ──▶ killed (terminal)

   fork(snapshot) ─────────▶ creating (a NEW sandbox id)

Isolation

Guest code is treated as hostile. Each VM boots under jailer (chroot + dropped privileges) in its own network namespace, with a per-VM tap device and double-NAT'd outbound internet. From inside a sandbox there is no route to the host, no route to the control plane, and no route to another sandbox; /dev/kvm and host files are unreachable. Isolation is enforced by construction, not by trusting the guest.

Billing — resource-seconds

spawnd bills allocated resource-seconds, not flat wall-clock, so cost scales with size. Both dimensions derive from the create-time allocation × time:

Allocation is fixed at create, so billing is deterministic and unforgeable — the guest cannot change its own vcpu/memMib.

API · Auth

The passwordless sign-in flow. No auth required to start it; the token is the credential.

curl -s -X POST https://spawnd.oonamy.xyz/auth/magic-link \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

curl -s 'https://spawnd.oonamy.xyz/auth/verify?token=THE_TOKEN'

curl -s https://spawnd.oonamy.xyz/auth/me \
  -H 'Authorization: Bearer <jwt>'

API · Keys

Session-authed key management. The console provisions your first key automatically.

curl -s https://spawnd.oonamy.xyz/v1/keys \
  -H 'Authorization: Bearer <jwt>'

curl -s -X POST https://spawnd.oonamy.xyz/v1/keys \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"ci"}'

API · Sandboxes

Authenticated with an org API key and scoped to the caller's org. A sandbox from another org returns 404.

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"template":"bigbox","metadata":{"job":"build-42"}}'

curl -s https://spawnd.oonamy.xyz/v1/sandboxes \
  -H 'Authorization: Bearer sk_live_...'

curl -s https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123 \
  -H 'Authorization: Bearer sk_live_...'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/exec \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"cmd":"python3","args":["-c","print(2+2)"]}'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/files \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"path":"/root/app.py","contentB64":"cHJpbnQoMSk="}'

curl -s 'https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/files?path=/root/app.py' \
  -H 'Authorization: Bearer sk_live_...'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/ports \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"port":8000}'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/pause \
  -H 'Authorization: Bearer sk_live_...'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/resume \
  -H 'Authorization: Bearer sk_live_...'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/snapshot \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"after-deps"}'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/fork \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"snapshotId":"snap_abc"}'

curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/stop \
  -H 'Authorization: Bearer sk_live_...'

curl -s -X DELETE https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123 \
  -H 'Authorization: Bearer sk_live_...'

API · Usage

Query the org's resource-seconds ledger over a time window.

curl -s 'https://spawnd.oonamy.xyz/v1/usage?from=2026-08-01T00:00:00Z&to=2026-08-07T00:00:00Z' \
  -H 'Authorization: Bearer sk_live_...'

Errors

Every API error is { code, message, retryable }. Only capacity is generally worth retrying.

CLI

The spawn CLI wraps the same REST API. Authenticate once with your org API key, then drive sandboxes from the terminal.

# create a bigbox, run a build, then tear it down
spawn bigbox
spawn exec sbx_123 -- cargo build --release
spawn rm sbx_123

MCP server

The orchestrator exposes sandbox control as an MCP server, so any MCP client — an IDE, an agent framework, an LLM app — can drive sandboxes as tools. Register it with your org API key as the bearer credential.

{
  "mcpServers": {
    "spawnd": {
      "url": "https://spawnd.oonamy.xyz/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Preview URLs

Expose a guest port to the public internet with POST /v1/sandboxes/:id/ports. The response url is http://<sandbox-id>--<workspace>.spawnd.oonamy.xyz — a single DNS label (double-dash separator) so one *.spawnd.oonamy.xyz wildcard covers every preview — routed by the HTTP Host header. Previews are org-scoped by construction and never outlive their VM — stopping or killing the sandbox deregisters the mapping.

# start a dev server in the sandbox, expose it, share the URL
spawn exec sbx_123 -- python3 -m http.server 8000 &
curl -s -X POST https://spawnd.oonamy.xyz/v1/sandboxes/sbx_123/ports \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' -d '{"port":8000}'
# → { "url": "http://sbx_123--acme.spawnd.oonamy.xyz" }

# routed by Host header, so it is testable locally:
curl -H 'Host: sbx_123--acme.spawnd.oonamy.xyz' http://127.0.0.1:8080/