Skip to main content
POST
Activate a sandbox

Authorizations

X-API-Key
string
header
required

Path Parameters

sandbox_id
string
required

The unique identifier of the sandbox. 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}$

Response

The sandbox is active.

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:
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).