Skip to main content
POST
Create a sandbox

Authorizations

Authorization
string
header
required

An API key (zode_tok_...). Create one in the console under API keys (https://console.zode.dev/tokens), or with zode login.

Query Parameters

environment
string

Body

application/json

A sandbox is one of the server's sizes, listed by GET /v1/images (images, the first is the default). The hosted API has four:

Leave out vcpus, ram_mb and disk_gb for small. Otherwise send vcpus, ram_mb or both, plus disk_gb if you like: every field sent must match the same size, else 400 invalid_request naming the sizes. disk_gb alone is 400. The size named default (as in the CLI and pricing) is not what an empty request gets.

name
string
Pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
vcpus
enum<integer>

Picks the size with this many vCPUs.

Available options:
2,
4,
8,
16
ram_mb
enum<integer>

Picks the size with this much RAM.

Available options:
4096,
8192,
16384,
32768
disk_gb
enum<integer>

Must be the disk of the size picked by vcpus or ram_mb.

Available options:
50,
110,
250
region
enum<string>
default:eu-central

eu-central is the only region today; more will be added.

Available options:
eu-central
git_repo
string
Maximum string length: 512
git_branch
string
Maximum string length: 255
pr_number
integer
Required range: x >= 1
max_cost_micros
integer<int64>

AI spend cap for this sandbox, in micro-dollars. Counts only AI calls made on the workspace's keys through the node's AI proxy, not compute or storage. The total is kept in the node daemon's memory, so a node daemon restart starts it again from zero. Reaching it refuses further AI calls (402 zode_spend_cap) and sends spend.cap_reached; the sandbox keeps running. Omitted means the workspace's per-sandbox default.

Required range: x >= 0
image
string

A ready custom image of the workspace (img_ id or name). It fixes the size and region: other values give 400.

browser
boolean

Switch the browser on; omitted means the workspace default.

desktop
boolean

Switch the desktop on; omitted means the workspace default.

Response

Created and running

id
string
required
Example:

"sbx_ilvsd743b36wqi26"

name
string
required
status
enum<string>
required
Available options:
creating,
running,
stopping,
stopped,
starting,
deleting,
deleted,
error
vcpus
integer
required
ram_mb
integer
required
disk_gb
integer
required
region
string
required
Example:

"eu-central"

git_repo
string
required
git_branch
string
required
pr_number
integer | null
required
max_cost_micros
integer<int64> | null
required

AI spend cap for this sandbox, in micro-dollars. Counts only AI calls made on the workspace's keys through the node's AI proxy, not compute or storage. The total is kept in the node daemon's memory, so a node daemon restart starts it again from zero. Reaching it refuses further AI calls (402 zode_spend_cap) and sends spend.cap_reached; the sandbox keeps running.

parent_sandbox_id
string | null
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
deleted_at
string<date-time> | null
required
created_by
null | object
required

The member who created or forked it; null for sandboxes made before this was recorded.

browser
boolean

Chrome with CDP is on.

desktop
boolean

The Linux desktop is on.

feature_error
string

Only on a create or fork whose browser or desktop could not be switched on; the sandbox was made.