Skip to main content
POST
Create new sandbox

Authorizations

x-api-key
string
header
required

Body

application/json

Provide exactly one start source: imageName (with optional imageId) or snapshotName (with optional snapshotId). vcpus, memMiB, and diskSizeMiB are only supported for image launches; snapshot launches always restore the snapshot's resources.

imageName
string
required

Image name to launch from (base image such as node, python, default, or a custom image).

imageId
string<uuid>

Pin a specific image revision. Requires imageName.

snapshotName
string

Memory snapshot name to restore from.

snapshotId
string<uuid>

Pin a specific snapshot revision. Requires snapshotName.

region
enum<string>
Available options:
us,
us-central,
us-west,
us-east,
asia-south,
europe-west
enableRecording
boolean
default:false
exposedPorts
object[]

Ports to expose at launch.

mounts
object

Volume mounts, keyed by absolute mount path inside the sandbox.

vcpus
integer

vCPU count (image launches only).

Required range: 1 <= x <= 32
memMiB
integer

Memory in MiB (image launches only).

Required range: 512 <= x <= 262144
diskSizeMiB
integer

Disk size in MiB (image launches only).

Required range: 2048 <= x <= 32768
timeoutMinutes
integer

Maximum sandbox lifetime in minutes, measured from VM start.

Required range: x <= 1440
allowInternetAccess
boolean
default:true

Outbound internet access policy.

allowOut
string[]

Outbound allow rules (IPv4 address, CIDR range, or domain).

denyOut
string[]

Outbound deny rules (IPv4 address or CIDR range).

Response

200 - application/json

Sandbox created

id
string<uuid>
required
status
enum<string>
required

Current sandbox lifecycle status.

Available options:
active,
closed,
close-error,
error
region
enum<string>
required
Available options:
us,
us-central,
us-west,
us-east,
asia-south,
europe-west
runtime
object
required

Connection details for the sandbox runtime API (process execution, files, terminals).

exposedPorts
object[]
required
teamId
string
startTime
number | null

Start timestamp in epoch milliseconds.

endTime
number | null

End timestamp in epoch milliseconds.

createdAt
string<date-time>
updatedAt
string<date-time>
closeReason
string | null
creditsUsed
number | null
vcpus
integer | null
memMiB
integer | null
diskSizeMiB
integer | null
timeoutMinutes
integer | null
network
object

Effective outbound network policy for a sandbox.

sessionUrl
string

Dashboard URL for this sandbox.

duration
number

Total runtime in milliseconds (0 while running).

proxyBytesUsed
number
token
string | null

Sandbox runtime session token (24h TTL). Null when the sandbox is unavailable.

tokenExpiresAt
string<date-time> | null