Skip to main content
POST
Create Sandbox Endpoint

Rate Limit

15,000 requests per 60 seconds per IP and token.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
name
string
required

Sandbox name

Required string length: 1 - 100
docker_image
string | null

Docker image to run. Required unless checkpoint_id is set.

Minimum string length: 1
checkpoint_id
string | null

Restore a checkpoint instead of booting an image. The sandbox takes the checkpoint's image and disk size, so docker_image and disk_size_gb must be omitted. The sandbox cold boots from the checkpoint's stored (DURABLE) disk; a checkpoint taken by pause can also restore memory, see restore_memory. Repeat to fork again. A checkpoint holds only the root disk, so no volume is mounted unless volumes is set. Only within the owning team or account.

Required string length: 1 - 64
restore_memory
boolean | null

With checkpoint_id: true restores the checkpoint's memory, so the new sandbox continues from the paused state with the paused shape (409 if it has none). Omitted or false cold boots from its disk. A memory fork is an exact copy of the paused guest: the kernel RNG is reseeded, but random generators seeded in userspace (OpenSSL, language runtimes) and keys, tokens, or IDs already in memory are the same in every fork. Rekey or regenerate them in the workload.

arch
enum<string>
default:amd64
Available options:
amd64,
arm64
start_command

A process to start without invoking a shell.

cpu_cores
integer
default:1

Whole vCPUs required

Required range: 1 <= x <= 48
memory_gb
number
default:1

Memory in GB

Required range: 0.1 <= x <= 128
disk_size_gb
number | null

Disk size in GB. Defaults to 32.

Required range: 0.1 <= x <= 1000
gpu_count
integer
default:0

Number of GPUs

Required range: 0 <= x <= 8
gpu_type
enum<string> | null

GPU type (e.g. H100, A100). Required when gpu_count > 0

Available options:
CPU_NODE,
A10_24GB,
A100_80GB,
A100_40GB,
A30_24GB,
A40_48GB,
B200_180GB,
B300_262GB,
GB200,
GB300,
RTX3070_8GB,
RTX3070_8GB,
RTX3080_10GB,
RTX3080Ti_12GB,
RTX3090_24GB,
RTX3090Ti_24GB,
RTX4070Ti_12GB,
RTX4080_16GB,
RTX4080Ti_16GB,
RTX4090_24GB,
RTX5090_32GB,
H100_80GB,
H200_96GB,
GH200_96GB,
H200_141GB,
GH200_480GB,
GH200_624GB,
L4_24GB,
L40_48GB,
L40S_48GB,
RTX4000_8GB,
RTX5000_16GB,
RTX6000_24GB,
RTX8000_48GB,
RTX2000Ada_16GB,
RTX4000Ada_20GB,
RTX5000Ada_32GB,
RTX6000Ada_48GB,
A2000_6GB,
A4000_16GB,
A4500_20GB,
A5000_24GB,
A6000_48GB,
V100_16GB,
V100_32GB,
P100_16GB,
T4_16GB,
P4_8GB,
P40_24GB,
RTX_PRO_6000B_96GB,
MI355X_288GB
vm
boolean
default:true

Sandbox runtime selector. VM is the only supported runtime: omit to use a VM. An explicit false is rejected with HTTP 410; the container runtime is retired. VM is required when requesting GPUs.

network_allowlist
string[] | null

VM only. Allow egress only to these domains/IPv4 CIDRs (hostname-aware; empty list denies all). Mutually exclusive with network_denylist. Entries may end in :port or :low-high (domains: :80 or :443 only) to match only those destination ports.

network_denylist
string[] | null

VM only. Deny egress to these domains/IPv4 CIDRs and allow everything else (empty list allows all). Mutually exclusive with network_allowlist. Entries may end in :port or :low-high (domains: :80 or :443 only) to match only those destination ports.

network_rules
Network Rules · object | null

VM only. Per-host HTTPS request header substitution rules: each key is a rule host (exact DNS name or a single-level wildcard such as *.example.com), each value maps header names to templates that may reference platform secrets owned by the sandbox's owner with ${prime.secrets.}. A rule never grants egress; the host must also be allowed by the allow/deny lists, and rules apply to HTTPS requests only. Substitution happens on the sandbox's node; the secret value never enters the sandbox.

timeout_minutes
integer
default:60

Max execution time in minutes. Defaults to 60. Use any negative value for no lifetime deadline.

idle_timeout_minutes
integer | null

Terminate the sandbox if no exec, upload, download, or read-file operation is active for this many minutes. Unset disables it.

environment_vars
Environment Vars · object | null

Environment variables

secrets
Secrets · object | null

Sensitive environment variables. VM values are encrypted server-side with tenant- and sandbox-bound authenticated encryption before dispatch.

labels
string[]

Tags/labels for the sandbox

volumes
VolumeMountSpec · object[]

VM only. Up to 8 volumes to mount, resolved by name in the caller's scope (team_id selects the team scope). Mount paths are absolute, normalized, unique, and never nested. Each volume is mounted at its current published head, also when the sandbox restores or forks a checkpoint (a disk restore only; memory restore rejects volumes). Unpublished writes are not carried.

Maximum array length: 8
team_id
string | null

Team ID for team sandboxes

advanced_configs
AdvancedConfigs · object | null

Advanced configuration options

registry_credentials_id
string | null

Retired: private-registry credentials are not supported. Any supplied value returns HTTP 410.

guaranteed
boolean
default:false

Admin/manager only. When true, schedule the sandbox with full CPU/memory requests and disk requests equal to the configured disk size, bypassing cluster resource multipliers. Not applicable to VM sandboxes.

idempotency_key
string | null

Client-generated key used to deduplicate retried create requests.

Required string length: 1 - 128

Response

Successful Response

id
string
required
name
string
required
dockerImage
string
required
startCommand
required

A process to start without invoking a shell.

cpuCores
number
required
memoryGB
number
required
diskSizeGB
number
required
diskMountPath
string
required
gpuCount
integer
required
status
enum<string>
required
Available options:
PENDING,
PROVISIONING,
RUNNING,
PAUSED,
ERROR,
TERMINATED,
TIMEOUT
timeoutMinutes
integer
required
environmentVars
Environmentvars · object | null
required
advancedConfigs
Advancedconfigs · object | null
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
startedAt
string<date-time> | null
required
terminatedAt
string<date-time> | null
required
userId
string | null
required
teamId
string | null
required
kubernetesJobId
string | null
required
gpuType
enum<string> | null
Available options:
CPU_NODE,
A10_24GB,
A100_80GB,
A100_40GB,
A30_24GB,
A40_48GB,
B200_180GB,
B300_262GB,
GB200,
GB300,
RTX3070_8GB,
RTX3070_8GB,
RTX3080_10GB,
RTX3080Ti_12GB,
RTX3090_24GB,
RTX3090Ti_24GB,
RTX4070Ti_12GB,
RTX4080_16GB,
RTX4080Ti_16GB,
RTX4090_24GB,
RTX5090_32GB,
H100_80GB,
H200_96GB,
GH200_96GB,
H200_141GB,
GH200_480GB,
GH200_624GB,
L4_24GB,
L40_48GB,
L40S_48GB,
RTX4000_8GB,
RTX5000_16GB,
RTX6000_24GB,
RTX8000_48GB,
RTX2000Ada_16GB,
RTX4000Ada_20GB,
RTX5000Ada_32GB,
RTX6000Ada_48GB,
A2000_6GB,
A4000_16GB,
A4500_20GB,
A5000_24GB,
A6000_48GB,
V100_16GB,
V100_32GB,
P100_16GB,
T4_16GB,
P4_8GB,
P40_24GB,
RTX_PRO_6000B_96GB,
MI355X_288GB
vm
boolean
default:false
network_allowlist
string[] | null
network_denylist
string[] | null
idleTimeoutMinutes
integer | null
terminationReason
string | null
labels
string[]
exitCode
integer | null
errorType
string | null
errorMessage
string | null
registryCredentialsId
string | null
pendingImageBuildId
string | null

Set while the sandbox is PENDING because its VM image artifact is being built automatically (first VM use of this image). The sandbox starts on its own once the build completes.

gatewayAuth
SandboxAuthResponse · object | null

Gateway credentials, returned on create when the API token has sandbox:read. Same payload as POST /sandbox/{id}/auth.