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://api.spawnd.sh.

1. Request a magic link

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

   Copy

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

2. Verify to get a session JWT

   Copy

   curl -s 'https://api.spawnd.sh/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://api.spawnd.sh/v1/keys \
     -H 'Authorization: Bearer <jwt>' \
     -H 'Content-Type: application/json' \
     -d '{"name":"cli"}'
   # → { "key": "e2b_...", "keyRecord": { "prefix": "e2b_...", ... } }

4. Create a sandbox and exec

   Copy

   curl -s -X POST https://api.spawnd.sh/v1/sandboxes \
     -H 'Authorization: Bearer e2b_...' \
     -H 'Content-Type: application/json' -d '{"template":"base"}'
   # → { "id": "sbx_123", "state": "running", ... }
   
   
   curl -s -X POST https://api.spawnd.sh/v1/sandboxes/sbx_123/exec \
     -H 'Authorization: Bearer e2b_...' \
     -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://api.spawnd.sh/v1/sandboxes/sbx_123 \
     -H 'Authorization: Bearer e2b_...'
   # → { "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 e2b_...

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://api.spawnd.sh/auth/magic-link \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

curl -s 'https://api.spawnd.sh/auth/verify?token=THE_TOKEN'

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

API · Keys

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

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

curl -s -X POST https://api.spawnd.sh/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://api.spawnd.sh/v1/sandboxes \
  -H 'Authorization: Bearer e2b_...' \
  -H 'Content-Type: application/json' \
  -d '{"template":"bigbox","metadata":{"job":"build-42"}}'

curl -s https://api.spawnd.sh/v1/sandboxes \
  -H 'Authorization: Bearer e2b_...'

curl -s https://api.spawnd.sh/v1/sandboxes/sbx_123 \
  -H 'Authorization: Bearer e2b_...'

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

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

curl -s 'https://api.spawnd.sh/v1/sandboxes/sbx_123/files?path=/root/app.py' \
  -H 'Authorization: Bearer e2b_...'

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

curl -s -X POST https://api.spawnd.sh/v1/sandboxes/sbx_123/pause \
  -H 'Authorization: Bearer e2b_...'

curl -s -X POST https://api.spawnd.sh/v1/sandboxes/sbx_123/resume \
  -H 'Authorization: Bearer e2b_...'

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

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

curl -s -X POST https://api.spawnd.sh/v1/sandboxes/sbx_123/stop \
  -H 'Authorization: Bearer e2b_...'

curl -s -X DELETE https://api.spawnd.sh/v1/sandboxes/sbx_123 \
  -H 'Authorization: Bearer e2b_...'

API · Usage

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

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

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://api.spawnd.sh/mcp",
      "headers": { "Authorization": "Bearer e2b_..." }
    }
  }
}

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.online — a single DNS label (double-dash separator) so one *.spawnd.online 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://api.spawnd.sh/v1/sandboxes/sbx_123/ports \
  -H 'Authorization: Bearer e2b_...' \
  -H 'Content-Type: application/json' -d '{"port":8000}'
# → { "url": "http://sbx_123--acme.spawnd.online" }


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

SSH available

SSH is the human interface to a sandbox. Everything an agent needs is in the REST API; SSH exists so a person can work in a sandbox with the tools they already use — scp, rsync, git, and editor Remote-SSH — none of which speak our API. Each sandbox is single-tenant, so you log in as root.

1 · Add your public key, once

Paste ~/.ssh/id_ed25519.pub into Settings → SSH keys. The key is stored on your organization and authorizes every sandbox the org creates — there is nothing to configure per sandbox. No private key ever leaves your machine, and if you do not have a key yet:

ssh-keygen -t ed25519 -C "$(whoami)@$(hostname)"

2 · Connect

A sandbox with SSH wired reports an ssh object on GET /v1/sandboxes/:id, and the console shows the same command. The host is the sandbox's preview name; the port is allocated per sandbox and is stable for its lifetime, so it is safe to put in ~/.ssh/config.

ssh -p 34211 root@sbx_123--acme.spawnd.online


# file transfer, sync, and Remote-SSH all work — it is a real sshd
scp -P 34211 app.tar.gz root@sbx_123--acme.spawnd.online:/root/
rsync -e 'ssh -p 34211' -a ./src/ root@sbx_123--acme.spawnd.online:/root/src/
code --remote ssh-remote+sbx_123--acme.spawnd.online:34211 /root


# or let the CLI find the port for you (and resume the sandbox if it is paused)
spawn ssh sbx_123
spawn ssh-config sbx_123 >> ~/.ssh/config

Host keys

Every sandbox generates its own ed25519 host key on first boot, so two sandboxes are never the same host to your SSH client. The fingerprint is published on the sandbox — compare it on first connect, or let spawn ssh-config write the known_hosts entry for you. You should never need StrictHostKeyChecking=no; if a fingerprint changes on a sandbox you did not recreate, stop and tell us.

Behaviour worth knowing