Skip to main content
POST
/
v1
/
sandboxes
import requests url = "https://api.13-215-85-171.sslip.io/v1/sandboxes" payload = {} headers = { "Idempotency-Key": "<idempotency-key>", "Authorization": "Bearer <token>", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.text)
{ "id": "sb_a1b2c3d4", "config": { "vcpus": 123, "memory_mb": 123, "disk_mb": 123 }, "template": "<string>", "created_at": "2023-11-07T05:31:56Z", "metadata": {}, "started_at": "2023-11-07T05:31:56Z", "timeout_ms": 123, "timeout_at": "2023-11-07T05:31:56Z", "expires_at": "2023-11-07T05:31:56Z", "cwd": "<string>", "traffic_access_token": "<string>", "warm_pool_checkout": { "hit": true, "id": "<string>" } }

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Headers

​
Idempotency-Key
string
required

Reuse the same key to safely retry the same create, reusable snapshot create, fork, upload create/complete, or agent deployment create operation without duplicating work.

Body

application/json
​
snapshot_id
string

Durable reusable snapshot ID to restore into a fresh sandbox. When provided, sizing, template, environment, filesystem, and VM egress policy are taken from the snapshot; each create idempotency key creates at most one child sandbox and the snapshot remains reusable for additional create requests.

​
warm_pool
object

Optional custom template warm-pool selector for sandbox create. V1 requires an explicit id for prefer and require modes; bypass may omit id to force cold create.

​
template
string
default:base

Template name or Docker image

​
vcpus
integer
default:1
Required range: x >= 1
​
memory_mb
integer
default:256
Required range: x >= 1
​
disk_mb
integer

Minimum rootfs size in MiB. On cold create the rootfs is grown to this size before boot. For snapshot-backed templates the disk size is fixed at build time, so disk_mb must not exceed the template's built-in size (rebuild the template with a larger disk_mb instead). Omit to use the default headroom. Not permitted with snapshot_id.

Required range: 512 <= x <= 131072
​
timeout_ms
integer
default:300000

Sandbox auto-destroy timeout in milliseconds

​
timeout_action
enum<string>
Available options:
destroy,
hibernate
​
auto_resume
boolean
default:false

When true, a hibernated sandbox is automatically resumed when a command, file, PTY, desktop, or proxy route targets its original sandbox ID. Requires timeout_action: hibernate or lifecycle.on_timeout: pause.

​
envs
object
​
metadata
object

Arbitrary user-supplied metadata attached to the sandbox; stored verbatim (any JSON object), deliberately open.

​
internet_access
boolean
default:true

When false, the sandbox has no network connectivity.

​
cwd
string | null

Optional default working directory for sandbox commands. Must be an absolute sandbox path that stays within the sandbox root. Accepted values are normalized before persistence, and reserved runtime paths under /workspace/.nullspace are rejected. When omitted, commands inherit the template default workdir; the standard agent-oriented templates default to /workspace. Clients may send an explicit null, which is treated the same as omitting the field.

​
desktop
object
​
network
object
​
volumes
object[] | null

Create-time shared-volume mount requests. ref is the canonical selector and accepts either an exact volume name or a volume id. On snapshot resume and fork, shared mounts are remounted with fresh internal leases before the new sandbox becomes ready; that storage remount does not make VM memory or mutable rootfs state portable across incompatible runtime hosts.

Maximum array length: 8
​
lifecycle
object

Response

Sandbox created

​
id
string
required
Example:

"sb_a1b2c3d4"

​
status
enum<string>
required
Available options:
creating,
running,
paused,
destroyed,
error
​
config
object
required
​
template
string
required
​
created_at
string<date-time>
required
​
metadata
object

Sandbox metadata. Attached volume state is exposed under volume_attachments in request order. Free-form user-supplied object stored verbatim; deliberately open.

​
started_at
string<date-time>
​
timeout_ms
integer<int64>
​
timeout_at
string<date-time>
​
expires_at
string<date-time>

Alias of timeout_at for clients that expect an expiry timestamp field.

​
timeout_action
enum<string>
Available options:
destroy,
hibernate
​
cwd
string

Normalized default working directory for this sandbox when one was configured.

​
traffic_access_token
string

Opaque token returned at create time. Send it as x-nullspace-traffic-access-token when network.allow_public_traffic is false.

​
warm_pool_checkout
object

Create-time warm-pool checkout result. Omitted when create did not consider a warm pool.