Fork a sandbox

Creates `count` new running sandboxes that share the source's memory and disk copy-on-write, each with a fresh identity (its own id, entropy, machine ID and clock; the source's environment, secrets, files and running processes carry over). The source must have been created with `forkable: true` (forkable sandboxes are restored for themselves rather than claimed from a pool, and track the pages they change); forks are forkable too. The source pauses while its changed memory is written (`pause`, `base`, `snapshot`, `export` phases in `Server-Timing`), then runs on; like a snapshot this resets its open connections to the outside. Each fork counts against your sandbox concurrency.

POST /v1/sandboxes/{sandbox_id}/fork
Creates `count` new running sandboxes that share the source's memory and disk copy-on-write, each with a fresh identity (its own id, entropy, machine ID and clock; the source's environment, secrets, files and running processes carry over). The source must have been created with `forkable: true` (forkable sandboxes are restored for themselves rather than claimed from a pool, and track the pages they change); forks are forkable too. The source pauses while its changed memory is written (`pause`, `base`, `snapshot`, `export` phases in `Server-Timing`), then runs on; like a snapshot this resets its open connections to the outside. Each fork counts against your sandbox concurrency.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Path Parameters

sandbox_id string required path
The sandbox ID (`sbx_…`).
Example: "sbx_01m5t68q1b590rj801nbzsqzkk"

Header Parameters

Idempotency-Key string optional header
A unique value (for example a UUID) that makes this request safe to retry. Scoped to your project for 24 hours: a retry with the same key, method, path and body returns the stored response with `Idempotent-Replayed: true`, and only to the same API key. Reusing the key for a different request returns `409 idempotency_key_conflict`.

Request Body

application/json
count integer
metadata object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.

Responses

201 The forks.
application/json
object string REQUIRED
Enum: list
data object[] REQUIRED
Array of:
id string REQUIRED
object string REQUIRED
Enum: sandbox
status string REQUIRED
`running` → `paused` ↔ `running` → `stopped`. `failed` means the microVM crashed; its usage is final.
Enum: running, paused, stopped, failed
host_id string REQUIRED
The ID in host-safe form, used in port URLs.
template object REQUIRED
id string REQUIRED
name string REQUIRED
snapshot string | null REQUIRED
The snapshot the sandbox was restored from.
vcpu integer REQUIRED
memory_mib integer REQUIRED
disk_gib integer REQUIRED
timeout_s integer REQUIRED
on_idle string REQUIRED
Enum: stop, pause
expires_at string (date-time) REQUIRED
env object REQUIRED
secret_names string[] REQUIRED
Names of the variables set from `secrets` (values are never returned).
Array of: string
ports object[] REQUIRED
Array of:
port integer REQUIRED
public boolean REQUIRED
url string (uri) | null REQUIRED
Public ports: the long-lived preview URL, token included. Private ports: `null`; mint a URL with `POST /v1/sandboxes/{sandbox_id}/ports/{port}/url`.
api object REQUIRED
scopes string[] REQUIRED
Array of: string
spend_cap_usd number | null REQUIRED
The grant's own cap, or `null` when the creating principal's cap applies.
connections string[] REQUIRED
Array of: string
egress object REQUIRED
mode string REQUIRED
Enum: public, allowlist, deny
allow string[] REQUIRED
Array of: string
forkable boolean REQUIRED
created_at string (date-time) REQUIRED
started_at string (date-time) REQUIRED
paused_at string (date-time) | null REQUIRED
stopped_at string (date-time) | null REQUIRED
stop_reason string | null REQUIRED
Why the sandbox stopped.
Enum: deleted, timeout, failed, null
usage object REQUIRED
vcpu_ms integer REQUIRED
gib_ms integer REQUIRED
timing object
Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements.
total_ms number REQUIRED
metadata object REQUIRED
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
next_cursor string | null REQUIRED
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
402 The organization has no credits left, or the key reached its spend cap.
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such sandbox in this project (`sandbox_not_found`).
409 The sandbox was not created with `forkable` (`fork_unavailable`).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
501 Part of the contract but not available on this deployment yet (`not_implemented`).
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X POST 'https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/fork' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "count": 2}'
const response = await fetch('https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/fork', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "count": 2  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/sandboxes/sbx_01m5t68q1b590rj801nbzsqzkk/fork', headers=headers, json={  "count": 2})print(response.json())
201 Response 
{  "object": "list",  "data": [],  "next_cursor": null}
Previous Resume a sandbox
Next Run a command
Ask a question... ⌘I