Skip to main content
POST
/
sandboxes
Create a new sandbox
curl --request POST \
  --url https://api.superserve.ai/sandboxes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "from_template": "<string>",
  "timeout_seconds": 302400,
  "metadata": {
    "env": "prod",
    "owner": "agent-7"
  },
  "env_vars": {
    "OPENAI_API_KEY": "sk-...",
    "DEBUG": "1",
    "run_id": "7f3c-21"
  },
  "network": {
    "allow_out": [
      "api.openai.com",
      "*.github.com",
      "8.8.8.8/32"
    ],
    "deny_out": [
      "0.0.0.0/0"
    ]
  },
  "secrets": {
    "ANTHROPIC_API_KEY": "anthropic-prod",
    "GITHUB_TOKEN": "ghp-readonly"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "vcpu_count": 123,
  "memory_mib": 123,
  "snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "timeout_seconds": 123,
  "network": {
    "allow_out": [
      "api.openai.com",
      "*.github.com",
      "8.8.8.8/32"
    ],
    "deny_out": [
      "0.0.0.0/0"
    ]
  },
  "metadata": {
    "env": "prod",
    "owner": "agent-7"
  },
  "access_token": "<string>",
  "secrets": [
    {
      "env_key": "<string>",
      "secret_name": "<string>",
      "revoked": false
    }
  ]
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
name
string
required

Human-readable name for the sandbox.

Required string length: 1 - 64
​
from_template
string

Boot the sandbox from a template. Accepts either a template UUID or a name (e.g. superserve/base, superserve/python-3.11, superserve/node-22, or a team-owned name like my-python-env). The template must be owned by the caller's team OR be a curated system template (curated templates use the superserve/ name prefix). The template's vCPU, memory, and disk values are inherited by the sandbox — they cannot be overridden per-sandbox because the snapshot dictates VM shape. When omitted, defaults to superserve/base.

​
timeout_seconds
integer<int32>

Optional hard lifetime cap in seconds, measured from sandbox creation. When set, the sandbox is destroyed this many seconds after creation regardless of state (active, paused) or activity — the user asked for a hard deadline. When unset, the sandbox lives until explicitly paused or deleted. Maximum 604800 (7 days).

Required range: 1 <= x <= 604800
​
metadata
object

Flat string-to-string tags attached to the sandbox at creation. Useful for grouping, owner labels, environment, run IDs, etc.

Constraints

  • Strings only. Values must be strings. There is no type coercion: metadata.count=42 filters for the string "42".
  • At most 64 keys.
  • Each key may be at most 256 bytes.
  • Each value may be at most 2048 bytes (2 KB).
  • The serialized object may be at most 16384 bytes (16 KB) in total.
  • Keys starting with superserve. or _superserve (case- insensitive) are reserved for platform use and rejected.

Metadata can be updated after creation via PATCH /sandboxes/:id. Filter sandboxes by metadata via the metadata.{key} query parameter on GET /sandboxes.

Example:
{ "env": "prod", "owner": "agent-7" }
​
env_vars
object

Environment variables injected into every process inside the sandbox (terminal sessions, exec calls). Merged on top of any defaults set by the template's env build steps — caller keys win on conflict. Survive pause/resume.

Example:
{
  "OPENAI_API_KEY": "sk-...",
  "DEBUG": "1",
  "run_id": "7f3c-21"
}
​
network
object

Egress network rules for a sandbox. allow_out accepts CIDRs (e.g. 8.8.8.8/32) and domain names (e.g. api.openai.com, *.github.com). deny_out accepts CIDRs only. Private ranges (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16) are always blocked regardless of rules.

​
secrets
object

Bind team-stored credentials to environment variables inside the sandbox. Keys are env-var names; values are secret names from POST /secrets. The agent never sees the real value: it sees a proxy token in env, and the in-host enforcement daemon swaps the token for the real credential at egress.

Example:
{
  "ANTHROPIC_API_KEY": "anthropic-prod",
  "GITHUB_TOKEN": "ghp-readonly"
}

Response

Sandbox created

Single-sandbox shape — SandboxListItem plus access_token and bound secrets.

​
id
string<uuid>
​
name
string
​
status
enum<string>

Current state of the sandbox. active means running; paused means paused and awaiting resume. resuming is a transient state observed while the platform restores a paused sandbox (e.g. via auto-resume on /exec); clients should retry shortly.

Available options:
active,
paused,
resuming
​
vcpu_count
integer
​
memory_mib
integer
​
snapshot_id
string<uuid>

ID of the latest snapshot (present after a pause).

​
created_at
string<date-time>
​
timeout_seconds
integer<int32>

Hard lifetime cap in seconds from creation, if set at creation time. Absent when no cap was configured.

​
network
object

Current egress allow/deny rules, if any have been configured. Absent when the sandbox uses default network settings.

​
metadata
object

User-supplied tags attached at creation. Always present — sandboxes created without metadata return {} rather than being absent.

Example:
{ "env": "prod", "owner": "agent-7" }
​
access_token
string

Per-sandbox access token for data-plane operations (file upload/download, terminal). Pass as the X-Access-Token header.

​
secrets
object[]

Credentials bound to this sandbox. Each entry maps an env-var name visible to the agent to the secret name it resolves to. revoked=true when the underlying secret has been soft-deleted (the env var still holds the now-useless proxy token).