POST /v1/sandboxes

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

wait_for_state?string

wait_timeout_ms?integer

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

template?string

Pre-built template name or id. Mutually exclusive with image.

image?

name?string

type?string

Value in

"persistent"
"ephemeral"

region?string

pool?string

Host pool to place on, e.g. 'fast'. Omitted or 'general' = the general fleet only; a dedicated pool is never used for a create that does not name it, and must be enabled for the organization (403 pool_not_enabled). Region still applies within the pool.

Match^[a-z0-9][a-z0-9-]{0,31}$

pool_fallback?string

When pool has no room: 'any' places on the general fleet, 'none' fails with the no-capacity 503. Only valid with pool.

Default"any"

Value in

"any"
"none"

cpu?integer

Range1 <= value <= 16

ram_mb?integer

At most 32768, or up to 65536 (within your plan) when the root disk is a volume (root_volume).

Range128 <= value <= 65536

disk_gb?integer

At most 100, or up to 1000 (within your plan) when the root disk is a volume (root_volume).

Range1 <= value <= 1000

gpus?integer

Range0 <= value <= 8

env?

ssh_keys?array<string>

language?string

Value in

"python"
"bash"
"node"
"sh"

auto_stop_minutes?integer

Range0 <= value

auto_archive_days?integer

Range0 <= value

auto_delete_days?integer

Range0 <= value

auto_resume?boolean

Whether an inbound request to an exposed port wakes the sandbox while it is stopped or archived. false = only POST /start or /resume brings it back.

Defaulttrue

backup_interval_min?integer

Automatic recovery-backup interval in minutes. 0 disables; omitted defaults to 60.

Range0 <= value <= 43200

metadata?

expose?array<>

Itemsitems <= 8

volumes?

Volume mounts keyed by absolute guest path, e.g. {"/data": {"volume": "data"}}. At most 8; paths must not nest. The legacy array [{volume_id, mount_path, subpath, mode}] is also accepted.

secrets?array<|>

Org secrets this sandbox may spend. Nothing lands in the guest: no env var, no file, no placeholder. Read back with GET /v1/sandboxes/{id}/secrets.

Itemsitems <= 16

Response Body

`application/json`

curl -X POST "https://example.com/v1/sandboxes" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "name": "string",  "state": "string",  "host_id": "string",  "via": "string",  "warm": true,  "pool": "string",  "pool_fallback": "string",  "placed_pool": "string",  "exposed": [    {      "port": 0,      "url": "string",      "token": "string",      "public": true,      "protocol": "http",      "host": "string",      "public_port": 0,      "proxy_protocol": true,      "direct": true,      "direct_host": "string",      "direct_url": "string"    }  ],  "volume_mounts": [    {      "id": "string",      "sandbox_id": "string",      "volume_id": "string",      "volume_name": "string",      "mount_path": "string",      "read_only": true,      "subdir": "string",      "state": "pending",      "generation": 0,      "base_commit_id": "string",      "mounted_commit_id": "string",      "pinned_commit_id": "string",      "last_commit_id": "string",      "last_commit_at": "string",      "dirty_bytes": 0,      "unflushed": true,      "error": "string",      "share": "node",      "share_effective": "node",      "share_fallback_reason": "string",      "stale": true,      "durability": "commit",      "created_at": "string"    }  ]}

Empty

Authorization

Query Parameters

Request Body

Response Body

201application/json

401

`application/json`