Create a new sandbox
Creates a sandbox from a template (defaults to superserve/base when
from_template is omitted). When the request returns successfully,
the sandbox is ready to use — you can run commands against it
immediately.
New sandboxes use strict preview routing: only ports explicitly
published through /sandboxes/{sandbox_id}/preview-ports are reachable.
preview_access defaults newly published ports to public or private;
each publication may override that default independently.
Authorizations
Body
Human-readable name for the sandbox.
1 - 64Boot 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.
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).
1 <= x <= 604800Optional 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).
0 <= x <= 2592000Flat 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=42filters 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.
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.
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.
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.
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.
public, private Response
Sandbox created
Single-sandbox shape — SandboxListItem plus access_token and bound secrets.
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.
^(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}$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.
active, paused, resuming ID of the latest snapshot (present after a pause).
Auto-pause timeout in seconds, if configured. Absent when auto-pause is disabled.
Garbage-collection window for the paused state, if configured. Absent when auto-delete is disabled.
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.
Current egress allow/deny rules, if any have been configured. Absent when the sandbox uses default network settings.
User-supplied tags attached at creation. Always present — sandboxes created without metadata return {} rather than being absent.
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.
legacy_public, public, private Per-sandbox access token for data-plane operations (file
upload/download, terminal). Pass as the X-Access-Token
header.
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).