runtime_sandboxes_create
Idempotent
Create a Linux sandbox (Ubuntu with python3, node, bun, git, gcc and sudo). The free usage is spent first, then prepaid credit, with nothing to choose. Defaults: 2 vCPU / 4096 MiB / 4096 MiB disk, no time limit: it runs while it works and pauses after 60 idle seconds. Waits up to 60 seconds and returns its state; run commands once it is running. Without credit: 4 running sandboxes at once (a paused one holds no slot), each up to 2 vCPU / 4 GiB, 8 vCPU / 16 GiB in all, at most 10 sandboxes kept and 50 made a day; once the account holds credit, its sandboxes have paid limits and still spend the free usage first.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cpu | No | shared | |
| env | No | Environment variables for every command, terminal and SSH session in it (up to 32). Values are never shown again. | |
| name | No | Your handle for it. | |
| vcpu | No | At most 16 (2 without credit). | |
| wait | No | ||
| image | No | Start from this ready image: id, name, name:tag or name@version. Waits for its ready check. | |
| labels | No | Up to 32 key: value tags to filter by. | |
| region | No | ||
| diskMiB | No | At least 3072; at most 409600, 400 GiB (10240 without credit). | |
| funding | No | Accepted and ignored: free usage first, then credit. | |
| network | No | Rules from the first start: {internet, allow?, deny?, connect?}, as runtime_sandboxes_network_set. | |
| volumes | No | Up to 4 volumes: [{volumeId, path, mode?: rw or snapshot}]. | |
| autoWake | No | A request to a paused sandbox wakes it. | |
| pausable | No | Ignored since 5 October 2026: every sandbox can pause. | |
| snapshot | No | Start as a copy of a ready snapshot, on the snapshot's host; not with image. A memory snapshot's copy is its size; a disk snapshot's is the size asked, its disk at least the saved one. | |
| memoryMiB | No | At most 65536, 64 GiB (4096 without credit). | |
| onTimeout | No | pause | |
| tailscale | No | Paid: join your tailnet once running: {authKeySecret (a job secret's name), hostname?, tags?}. | |
| onLeaseEnd | No | onTimeout's older name. | |
| persistent | No | Paid: never pause it for idleness or a time limit. | |
| getOrCreate | No | With name: return the sandbox holding that name (woken if paused) instead of name_taken. | |
| maxCostMicros | No | Deprecated, still accepted: use maxTotalCostMicros. | |
| cpuFloorMillis | No | Guaranteed CPU, thousandths of a vCPU. | |
| idempotencyKey | No | Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error. | |
| timeoutSeconds | No | A time limit, 60 to 86400 s (24 h); 0, the default, is none: it runs while it works. | |
| idlePauseSeconds | No | Pause after this many idle seconds (no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes). Default 60; 0 never; otherwise 10 to 86400. | |
| maxTotalCostMicros | No | The most it may cost over its whole life. |