API Reference (Node Controller)

Base URL: https://api.sandbox.stateset.app/api/v1 The Node controller is the default deployed by k8s/deployment.yaml.

This API is served from api.sandbox.stateset.app, which is a different host from the commerce and agent APIs on api.stateset.com, and it takes a sandbox key rather than a platform key. A key that works against one will return 401 against the other.

Authentication

This API supports three auth modes:

API key (recommended for servers/CLI):

Authorization: ApiKey sk_your_api_key

Session JWT (recommended for same-origin apps):

Authorization: Bearer eyJhbGciOi...

Browser session cookie (recommended for dashboards):

stateset_session is an httpOnly cookie set by registration/login/invite accept/SSO callback.
For state-changing requests authenticated via the session cookie (POST/PUT/PATCH/DELETE), include X-CSRF-Token: <token>.
After you have a session cookie, the controller returns an x-csrf-token response header on safe requests (GET/HEAD/OPTIONS) and sets a __stateset_csrf cookie. Use that token value for subsequent writes.
Requests authenticated via an Authorization header (API key or Bearer JWT) do not require CSRF.

Errors

Errors are returned as:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication required"
  }
}

Health & Monitoring

GET /health

No auth.

GET /ready

No auth. Returns 503 if not ready.

GET /health/detailed

No auth.

GET /metrics

Internal auth in production (X-Internal-Token or Authorization: Bearer <internal-key>).

Authentication Endpoints

POST /register

Creates an organization + user + API key and sets a session cookie. Request:

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "organization_name": "Example Co",
  "email": "ada@example.com",
  "password": "SecurePassword123!",
  "use_case": "AI agent development"
}

Response:

{
  "organization": { "id": "org_...", "name": "Example Co", "slug": "example-co", "plan": "hobby" },
  "user": { "id": "usr_...", "email": "ada@example.com", "role": "owner" },
  "api_key": { "key": "sk_test_...", "key_prefix": "sk_test_...", "name": "Default API Key" },
  "token": "eyJhbGciOi..."
}

Authenticates and returns a session payload (also sets stateset_session cookie). Request:

{ "email": "ada@example.com", "password": "SecurePassword123!" }

Response:

{
  "token": "eyJhbGciOi...",
  "expiresAt": "2030-01-01T00:00:00.000Z",
  "user": {
    "id": "usr_...",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "role": "owner",
    "emailVerified": false
  },
  "organization": {
    "id": "org_...",
    "name": "Example Co",
    "slug": "example-co",
    "plan": "hobby"
  }
}

POST /auth/logout

Clears the session cookie.

GET /auth/providers

Returns which optional auth providers are configured. Response shape:

{
  "workos": {
    "enabled": true,
    "redirect_uri": "https://sandbox.stateset.com/auth/callback"
  }
}

GET /auth/session

Returns the current session payload (same shape as /auth/login). Auth: cookie session (stateset_session) or Authorization: Bearer <token>.

GET /auth/workos/authorize

Starts WorkOS AuthKit SSO. Redirects to WorkOS and sets short-lived PKCE cookies. Requires WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_REDIRECT_URI. Query params:

return_to: redirect destination after successful login (same-origin relative paths only; protocol-relative values like //example.com are rejected)
organization_id, connection_id, domain_hint, login_hint, screen_hint: WorkOS hints

GET /auth/workos/callback

WorkOS callback. Exchanges code for user identity, then sets a stateset_session cookie and redirects back.

GET /auth/workos/link

Returns the current WorkOS linking status for the authenticated organization. Auth: cookie session (admin/owner).

POST /auth/workos/link

Links a WorkOS Organization ID to the authenticated organization. Auth: cookie session (owner). Request:

{ "workos_organization_id": "workos_org_..." }

DELETE /auth/workos/link

Unlinks WorkOS from the authenticated organization. Auth: cookie session (owner). When AUDIT_LOGS_ENABLED=true, WorkOS link/unlink operations emit audit actions:

auth.sso.link
auth.sso.unlink

Sandboxes

POST /sandbox/create

Creates a new sandbox. Request:

{
  "cpus": "2",
  "memory": "2Gi",
  "timeout_seconds": 600,
  "isolation": "wasm",
  "env": { "EXAMPLE": "true" },
  "wasm_network": {
    "enabled": true,
    "allow_tcp": true,
    "allow_udp": false,
    "allow_ip_lookup": true
  }
}

Notes:

isolation supports container, gvisor, microvm, and wasm.
wasm_network is valid only when isolation is wasm.

Response:

{
  "sandbox_id": "f3533033-a515-4f29-a440-74ab29021be5",
  "org_id": "org_...",
  "session_id": "1c3a...",
  "status": "running",
  "pod_ip": "10.34.3.135",
  "created_at": "2026-01-16T03:24:05.549Z",
  "expires_at": "2026-01-16T03:34:05.549Z",
  "startup_metrics": { "total_ms": 2634 }
}

GET /sandboxes?limit=20&offset=0

Lists sandboxes for the authenticated organization.

GET /sandbox/:id

Returns sandbox details.

GET /sandbox/:id/status

Returns status + expiry (lightweight).

POST /sandbox/:id/stop

Stops/deletes the sandbox. Alias:

DELETE /sandbox/:id

Command Execution

POST /sandbox/:id/execute

Executes a command in the sandbox. Request:

{
  "command": ["python3", "-c", "print(\"hello\")"],
  "working_dir": "/workspace",
  "env": { "DEBUG": "true" },
  "timeout": 60000,
  "stream": false
}

Response (non-streaming):

{ "exit_code": 0, "stdout": "hello\n", "stderr": "" }

Streaming (SSE):

Set "stream": true
Response Content-Type: text/event-stream
Events are emitted as data: {...}\n\n with type values: stdout, stderr, exit, done, error

File Operations

File contents are base64 encoded.

POST /sandbox/:id/files

Writes one or more files. Request:

{
  "files": [
    { "path": "/workspace/main.py", "content": "cHJpbnQoImhlbGxvIikK" }
  ]
}

GET /sandbox/:id/files?path=/workspace/main.py

Reads a file (JSON response containing base64 content).

GET /sandbox/:id/files/download?path=/workspace/main.py

Downloads a file as application/octet-stream.

REPL Sessions

Interactive Python REPL with persistent session state. Variables and imports survive across execute calls. Requires REPL_ENABLED=true.

POST /sandbox/:id/repl/sessions

Creates a new REPL session. Request:

{ "language": "python" }

language is optional and defaults to python. Response:

{
  "session": {
    "id": "repl_01H...",
    "sandboxId": "f3533033-a515-4f29-a440-74ab29021be5",
    "language": "python",
    "kernelId": "k_abc123",
    "status": "idle"
  }
}

GET /sandbox/:id/repl/sessions

Lists REPL sessions for a sandbox. Response:

{
  "sessions": [
    {
      "id": "repl_01H...",
      "sandboxId": "f3533033-a515-4f29-a440-74ab29021be5",
      "language": "python",
      "kernelId": "k_abc123",
      "status": "idle"
    }
  ]
}

POST /sandbox/:id/repl/sessions/:sessionId/execute

Executes code in a REPL session. Variables and imports persist across calls. Request:

{ "code": "x = 42\nprint(x)" }

Response:

{
  "executionCount": 1,
  "outputs": [
    { "type": "stdout", "text": "42\n" },
    { "type": "result", "data": { "text/plain": "42" } }
  ],
  "status": "ok",
  "durationMs": 15
}

POST /sandbox/:id/repl/sessions/:sessionId/stream

Executes code with streaming output via SSE. Request:

{ "code": "for i in range(5): print(i)" }

Response Content-Type: text/event-stream. Events are emitted as output is produced:

event: output
data: {"type":"stdout","text":"0\n"}

event: output
data: {"type":"stdout","text":"1\n"}

event: done
data: {"executionCount":2,"status":"ok","durationMs":25}

POST /sandbox/:id/repl/sessions/:sessionId/interrupt

Interrupts a running execution in the session. Response:

{ "status": "interrupted" }

DELETE /sandbox/:id/repl/sessions/:sessionId

Destroys a REPL session and its kernel. Response:

{ "status": "destroyed" }

Session Status Values

Status	Description
`starting`	Kernel is being provisioned
`idle`	Ready for code execution
`busy`	Currently executing code
`dead`	Kernel crashed or was destroyed

Output Types

Type	Description
`stdout`	Standard output text
`stderr`	Standard error text
`result`	Execution result (rich MIME data in `data` field)
`error`	Execution error with `name`, `value`, and `traceback` fields

Templates

GET /templates

Lists templates (summaries).

GET /templates/categories

Lists categories.

GET /templates/:id

Returns a template including file contents.

POST /sandbox/create-from-template

Creates a sandbox based on a template.

Secrets (BYOK)

Secrets are organization-scoped and injected into sandbox pods as environment variables.

POST /secrets

Creates a secret.

GET /secrets

Lists secrets (values are never returned).

PUT /secrets/:name

Updates a secret.

DELETE /secrets/:name

Deletes a secret.

API Keys

GET /api-keys

Lists API keys for the organization.

POST /api-keys

Creates a new API key (the plaintext key is only returned once).

DELETE /api-keys/:id

Revokes an API key.

POST /api-keys/:id/regenerate

Regenerates a key (returns a new plaintext key).

GitHub Integrations

These routes are available when GitHub integration routes are enabled.

GET /github/installations

Lists linked/pending GitHub App installations for the authenticated organization.

POST /github/installations/:id/connect

Links an installation to the authenticated organization.

DELETE /github/installations/:id

Removes a linked installation from the authenticated organization.

GET /github/settings

Returns GitHub automation settings for the organization. Includes auto_pr_comment_on_sandbox to control whether PR-triggered sandboxes post an automatic GitHub comment with dashboard/sandbox details. Includes auto_stop_sandbox_on_pr_close to control whether PR-triggered sandboxes are automatically stopped when the pull request is closed.

PUT /github/settings

Updates GitHub automation settings.

GET /github/events

Returns recent GitHub webhook processing events for the organization.

GET /github/health?window_hours=24

Returns integration health summary (installations, webhook success/failure counts, status, latest event/failure).

window_hours is optional and must be an integer between 1 and 168.

Internal Snapshot API (`/internal`)

These endpoints require internal auth (X-Internal-Token or Authorization: Bearer <internal-token>) in production.

GET /internal/snapshots

List all snapshot profiles. Response:

{
  "snapshots": [
    {
      "profileKey": "2vcpu-2048mb",
      "memoryPath": "/var/lib/firecracker/snapshots/2vcpu-2048mb/memory.bin",
      "statePath": "/var/lib/firecracker/snapshots/2vcpu-2048mb/state.bin",
      "createdAt": "2026-02-20T12:00:00.000Z",
      "vcpuCount": 2,
      "memSizeMib": 2048,
      "snapshotType": "full",
      "memoryBackend": "file",
      "version": 1
    }
  ],
  "total": 1,
  "enabled": true
}

GET /internal/snapshots/status

Snapshot service health and configuration.

{
  "enabled": true,
  "snapshotCount": 1,
  "snapshotDir": "/var/lib/firecracker/snapshots",
  "memoryBackend": "file",
  "snapshotType": "full"
}

POST /internal/snapshots

Create a snapshot profile. Request example:

{
  "profile": "2vcpu-2048mb",
  "vcpu_count": 2,
  "mem_size_mib": 2048,
  "kernel_path": "/var/lib/firecracker/kernel/vmlinux",
  "rootfs_path": "/var/lib/firecracker/rootfs/rootfs.ext4"
}

GET /internal/snapshots/:profileKey

Get metadata for a single profile.

DELETE /internal/snapshots/:profileKey

Delete a snapshot profile.

POST /internal/snapshots/:profileKey/restore

Restore a snapshot profile into a mock Firecracker runtime.

POST /internal/snapshots/warm

Warm cache, with optional body { "count": 3 }.

POST /internal/snapshots/cleanup

Remove old snapshots by age and/or keep policy. Request example:

{
  "keep_most_recent": 10,
  "max_age_seconds": 86400,
  "dry_run": true
}

Response example:

{
  "message": "Snapshot cleanup completed",
  "dry_run": true,
  "profiles_removed": 2,
  "removed_profiles": [
    "1vcpu-512mb",
    "2vcpu-1024mb"
  ],
  "profiles_removed_by_age": 1,
  "profiles_removed_by_keep_limit": 1,
  "total_found": 4,
  "total_remaining": 2
}

Idempotency

POST endpoints support safe retries via the Idempotency-Key header. When enabled (IDEMPOTENCY_ENABLED=true, default), the controller caches the response for each unique (orgId, key, route) tuple for 24 hours.

Usage

POST /api/v1/sandbox/create
Authorization: ApiKey sk_...
Idempotency-Key: my-unique-request-id-123
Content-Type: application/json

Behavior

First request: Executes normally. Response is stored and returned with Idempotency-Status: stored.
Replay: If the same (orgId, key, route) is seen again within 24h, the cached response is returned with Idempotency-Status: replayed.
Body mismatch: If a replay has a different request body hash, the server returns 409 Conflict with error code IDEMPOTENCY_KEY_REUSE_MISMATCH.
Scope: POST requests only. The header is ignored on GET/PUT/PATCH/DELETE.
TTL: 24 hours. After expiry the key can be reused.

Response Headers

Header	Values	Description
`Idempotency-Status`	`stored`, `replayed`	Whether the response was freshly computed or replayed from cache

Real-time Events (SSE)

GET /events/stream provides a Server-Sent Events stream of sandbox lifecycle events for the authenticated organization.

Authentication

Because the browser EventSource API does not support custom headers, this endpoint accepts auth via multiple mechanisms:

Authorization: Bearer <jwt> header
Authorization: ApiKey <key> header
?token=<jwt> query parameter
?apiKey=<key> query parameter (requires &orgId=<orgId>)
Session cookie (stateset_session)

Event Format

event: sandbox.created
id: evt_01H...
data: {"sandboxId":"sbx-abc","event":"sandbox.created","timestamp":"2026-02-27T12:00:00Z",...}

event: sandbox.stopped
id: evt_01H...
data: {"sandboxId":"sbx-abc","event":"sandbox.stopped",...}

Event Types

sandbox.created, sandbox.stopped, sandbox.deleted, artifact.uploaded, checkpoint.created, checkpoint.restored, mcp.tool_called, security.violation, resources.limit_warning

Resumable Streams

On reconnect, include the last received event ID to replay missed events:

Last-Event-ID request header (standard SSE reconnect)
?lastEventId=<id> query parameter

The server buffers recent events in memory and replays any events published after the given ID.

Heartbeat

A :heartbeat comment is sent every 20 seconds to keep the connection alive.

Concurrency Budgets & Queue Mode

Each organization has per-plan concurrency budgets for sandboxes and command executions.

Per-Plan Budgets

Plan	Max Concurrent Sandboxes	Max Concurrent Executions
Hobby	3	5
Pro	10	20
Team	25	50
Enterprise	100	200

Limits are configurable via ORG_BUDGET_<PLAN>_MAX_CONCURRENT_SANDBOXES and ORG_BUDGET_<PLAN>_MAX_CONCURRENT_EXECUTES environment variables.

Exceeding Limits

When a request would exceed the budget:

Without queue mode: 429 Too Many Requests with error code CONCURRENT_LIMIT_EXCEEDED.
With queue mode (QUEUE_MODE_ENABLED=true): 202 Accepted with a queued request ID.

Queued Response Format

{
  "status": "queued",
  "requestId": "req_abc123",
  "position": 3,
  "queue_depth": 5,
  "estimated_wait_seconds": 15
}

Queued Response Headers

Header	Description
`X-Stateset-Queue-Status`	`queued`
`X-Stateset-Queue-Position`	Position in queue
`Retry-After`	Seconds to wait before polling

Polling

GET /requests/:requestId returns the current status of a queued request, including position, queue_depth, and estimated_wait_seconds. Once completed, response_body and response_status are included.

Queue Health

GET /queue/health returns per-org queue telemetry: queue_depth, processing_count, oldest_queued_age_seconds, estimated_wait_seconds, and rolling-window statistics (completed_count, failed_count, expired_count, average_wait_ms, p95_wait_ms).

Error Codes

Code	Status	Description
`CONCURRENT_LIMIT_EXCEEDED`	429	Budget exceeded and queue mode is off
`QUEUE_DEPTH_EXCEEDED`	429	Queue is full (`QUEUE_MAX_DEPTH` reached)

Egress Policies

Per-organization outbound network policies. Requires EGRESS_POLICIES_ENABLED=true.

Policy Model

{
  "id": "pol_abc123",
  "organizationId": "org_...",
  "policyName": "default",
  "allowAll": false,
  "allowedDomains": ["api.github.com", "*.npmjs.org"],
  "deniedDomains": ["evil.example.com"],
  "allowedPorts": [80, 443],
  "logAllRequests": true
}

Domain Matching

Exact match: api.github.com matches only api.github.com
Wildcard: *.npmjs.org matches registry.npmjs.org, www.npmjs.org, etc.

Enforcement Modes (`EGRESS_PROXY_MODE`)

Mode	Behavior
`off`	No enforcement (default)
`monitor`	Log violations but allow all traffic
`enforce`	Block denied traffic, return `EGRESS_DENIED` (403)

Error Code

Code	Status	Description
`EGRESS_DENIED`	403	Request blocked by egress policy

Pagination

List endpoints support standard offset-based pagination.

Query Parameters

Parameter	Type	Default	Max	Description
`limit`	integer	100	1000	Number of items to return
`offset`	integer	0	—	Number of items to skip

Response Format

{
  "data": [...],
  "total": 42,
  "limit": 100,
  "offset": 0,
  "has_more": false
}

Endpoints that support pagination: /sandboxes, /artifacts, /checkpoints, /webhooks, /audit, /egress/audit, /requests.

Optional Features

Some routes are only registered when corresponding services are enabled and the database is configured.

REPL sessions: /sandbox/:id/repl/sessions, execute, stream, interrupt, destroy (REPL_ENABLED=true)
Checkpoints: /sandbox/:id/checkpoints, /checkpoints, …
Artifacts: /sandbox/:id/artifacts/upload, /artifacts, multipart uploads at /artifacts/uploads/initiate, /artifacts/uploads/:upload_id/parts/:part_number, /artifacts/uploads/:upload_id/complete, /artifacts/uploads/:upload_id/abort
Egress audit: /egress/audit (org query), /internal/egress/audit (proxy/internal ingest)
Egress authz adapter: /internal/egress/authorize (proxy authorization check)
Egress policy snapshot: /internal/egress/policies (proxy polling/sync)
Webhooks: /webhooks, …
Tunnels: /sandbox/:id/tunnels, …
Audit: /audit, /sandbox/:id/audit/summary

Queue/backpressure notes:

When a create/execute request is queued (202), responses include:
- X-Stateset-Queue-Status: queued
- X-Stateset-Queue-Position
- Retry-After
Queue poll (GET /requests/:requestId) includes position, queue_depth, and estimated_wait_seconds.
Queue health (GET /queue/health) returns per-org queue telemetry for dashboards:
- queue_depth, processing_count, oldest_queued_age_seconds
- estimated_wait_seconds, seconds_per_queue_position
- rolling-window counts and latency stats (completed_count, failed_count, expired_count, average_wait_ms, p95_wait_ms)

Next steps

Sandbox quickstart

Create and run your first sandbox against these endpoints.

Node SDK

The typed client over this API.

Python SDK

The same, for Python.

Operations

Health, metrics and runbooks for the controller serving this API.

Last modified on August 31, 2026

​API Reference (Node Controller)

​Authentication

​Errors

​Health & Monitoring

​GET /health

​GET /ready

​GET /health/detailed

​GET /metrics

​Authentication Endpoints

​POST /register

​POST /auth/login

​POST /auth/logout

​GET /auth/providers

​GET /auth/session

​GET /auth/workos/authorize

​GET /auth/workos/callback

​GET /auth/workos/link

​POST /auth/workos/link

​DELETE /auth/workos/link

​Sandboxes

​POST /sandbox/create

​GET /sandboxes?limit=20&offset=0

​GET /sandbox/:id

​GET /sandbox/:id/status

​POST /sandbox/:id/stop

​Command Execution

​POST /sandbox/:id/execute

​File Operations

​POST /sandbox/:id/files

​GET /sandbox/:id/files?path=/workspace/main.py

​GET /sandbox/:id/files/download?path=/workspace/main.py

​REPL Sessions

​POST /sandbox/:id/repl/sessions

​GET /sandbox/:id/repl/sessions

​POST /sandbox/:id/repl/sessions/:sessionId/execute

​POST /sandbox/:id/repl/sessions/:sessionId/stream

​POST /sandbox/:id/repl/sessions/:sessionId/interrupt

​DELETE /sandbox/:id/repl/sessions/:sessionId

​Session Status Values

​Output Types

​Templates

​GET /templates

​GET /templates/categories

​GET /templates/:id

​POST /sandbox/create-from-template

​Secrets (BYOK)

​POST /secrets

​GET /secrets

​PUT /secrets/:name

​DELETE /secrets/:name

​API Keys

​GET /api-keys

​POST /api-keys

​DELETE /api-keys/:id

​POST /api-keys/:id/regenerate

​GitHub Integrations

​GET /github/installations

​POST /github/installations/:id/connect

​DELETE /github/installations/:id

​GET /github/settings

​PUT /github/settings

​GET /github/events

​GET /github/health?window_hours=24

​Internal Snapshot API (/internal)

​GET /internal/snapshots

​GET /internal/snapshots/status

​POST /internal/snapshots

​GET /internal/snapshots/:profileKey

​DELETE /internal/snapshots/:profileKey

​POST /internal/snapshots/:profileKey/restore

​POST /internal/snapshots/warm

​POST /internal/snapshots/cleanup

​Idempotency

​Usage

​Behavior

​Response Headers

​Real-time Events (SSE)

​Authentication

​Event Format

​Event Types

API Reference (Node Controller)

Authentication

Errors

Health & Monitoring

GET /health

GET /ready

GET /health/detailed

GET /metrics

Authentication Endpoints

POST /register

POST /auth/login

POST /auth/logout

GET /auth/providers

GET /auth/session

GET /auth/workos/authorize

GET /auth/workos/callback

GET /auth/workos/link

POST /auth/workos/link

DELETE /auth/workos/link

Sandboxes

POST /sandbox/create

GET /sandboxes?limit=20&offset=0

GET /sandbox/:id

GET /sandbox/:id/status

POST /sandbox/:id/stop

Command Execution

POST /sandbox/:id/execute

File Operations

POST /sandbox/:id/files

GET /sandbox/:id/files?path=/workspace/main.py

GET /sandbox/:id/files/download?path=/workspace/main.py

REPL Sessions

POST /sandbox/:id/repl/sessions

GET /sandbox/:id/repl/sessions

POST /sandbox/:id/repl/sessions/:sessionId/execute

POST /sandbox/:id/repl/sessions/:sessionId/stream

POST /sandbox/:id/repl/sessions/:sessionId/interrupt

DELETE /sandbox/:id/repl/sessions/:sessionId

Session Status Values

Output Types

Templates

GET /templates

GET /templates/categories

GET /templates/:id

POST /sandbox/create-from-template

Secrets (BYOK)

POST /secrets

GET /secrets

PUT /secrets/:name

DELETE /secrets/:name

API Keys

GET /api-keys

POST /api-keys

DELETE /api-keys/:id

POST /api-keys/:id/regenerate

GitHub Integrations

GET /github/installations

POST /github/installations/:id/connect

DELETE /github/installations/:id

GET /github/settings

PUT /github/settings

GET /github/events

GET /github/health?window_hours=24

Internal Snapshot API (`/internal`)

GET /internal/snapshots

GET /internal/snapshots/status

POST /internal/snapshots

GET /internal/snapshots/:profileKey

DELETE /internal/snapshots/:profileKey

POST /internal/snapshots/:profileKey/restore

POST /internal/snapshots/warm

POST /internal/snapshots/cleanup

Idempotency

Usage

Behavior

Response Headers

Real-time Events (SSE)

Authentication

Event Format

Event Types