Skip to main content
POST
Create a new sandbox

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 auto-pause timeout in seconds. The sandbox is paused once its current active session has run this long; each resume starts a fresh window. When unset, the sandbox stays active until explicitly paused. Also settable later via PATCH /sandboxes/{sandbox_id}. Maximum 604800 (7 days).

Required range: 1 <= x <= 604800
auto_delete_seconds
integer<int32>

Optional garbage-collection window for paused sandboxes, in seconds. Once the sandbox has been continuously paused for this long it is deleted automatically. The window arms each time the sandbox pauses and is cancelled by resume, so a sandbox in use is never eligible. 0 deletes the sandbox as soon as it pauses. When unset, paused sandboxes are kept until explicitly deleted. Also settable later via PATCH /sandboxes/{sandbox_id}. Maximum 2592000 (30 days).

Required range: 0 <= x <= 2592000
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_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:
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:
preview_access
enum<string>
default:public

Default access for newly published preview ports. New sandboxes default to public; private ports stay closed with 401 until preview-token authentication is introduced. Both modes are strict: only explicitly published ports are reachable. legacy_public is reserved for sandboxes created before explicit publication and cannot be selected through the API.

Available options:
public,
private

Response

Sandbox created

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

id
string

Public sandbox ID: a bare UUID, or the region-tagged form sb-<region>-<uuid> (e.g. sb-use-1b4e28ba-…). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably.

Pattern: ^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
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>

Auto-pause timeout in seconds, if configured. Absent when auto-pause is disabled.

auto_delete_seconds
integer<int32>

Garbage-collection window for the paused state, if configured. Absent when auto-delete is disabled.

auto_delete_at
string<date-time>

When the sandbox will be deleted. Present only while the sandbox is paused with auto_delete_seconds configured. The deadline is armed when the sandbox pauses (or when the setting is applied to an already-paused sandbox) and cleared on resume.

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:
preview_access
enum<string>

Default access for newly published ports. public and private are strict modes; existing published rows keep their own access. legacy_public may be returned for an older sandbox and preserves all-port behavior until updated to a strict mode.

Available options:
legacy_public,
public,
private
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).