Create a sandbox

Claims a pre-warmed microVM from the template's pool (or restores a snapshot), binds a fresh identity to it (new entropy, machine ID and clock) and returns it running. The sandbox stops when `timeout_s` passes unless you extend it, and `on_idle: pause` pauses it instead. It bills `sandboxes.vcpu_ms` (CPU used) and `sandboxes.gib_ms` (memory allocated) while running. `api` grants code inside the sandbox access to B3OS (`http://127.0.0.1:7700`) with scopes that must be a subset of yours; `sandboxes:write`, every `vault:*` and every `platform:*` scope are never granted unless named explicitly. `api.spend_cap_usd` may not exceed your own spend cap, and `null` means your cap applies; scopes or a cap beyond yours are refused with `403 forbidden`, `reason: scope_escalation`. Inside the sandbox the environment also has `B3OS_API_URL=http://127.0.0.1:7700`, `B3OS_SANDBOX_ID`, `B3OS_PROJECT` and `B3OS_PORT_BASE_PATH=/sbx/<host_id>`. `B3OS_PORT_BASE_PATH` is only the fixed start of every port preview path on `usercontent.b3os.org`, not a full base path: the full prefix of a request, `/sbx/<host_id>/<port>/<token>`, arrives with it in `X-Forwarded-Prefix` (`sandboxesProxyPortGet`). `timing` phases: `validate_ms`, then `claim_ms` and `resume_ms` for a pre-warmed microVM from the pool, or `restore_ms` when none was parked (a restore on demand, or from a snapshot), then `bind_ms` (the identity and environment reach the guest agent), and `total_ms`. A create that has started finishes even if the client disconnects before the response: the sandbox then runs (and is billed) until its timeout or a delete, and `GET /v1/sandboxes` lists it with the `metadata` it was created with. After a disconnect, look for it there before you retry: a retry is a new create, also with the same `Idempotency-Key`, because the key is released when the client goes away before the response. Fork, snapshot, pause and resume also finish after a disconnect.

POST /v1/sandboxes

Authentication

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

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

template string

Template name or `tpl_` ID. Ignored when `snapshot` is set.

snapshot string

Restore this snapshot instead of starting from a template.

vcpu integer

Virtual CPUs (plan maximum in `GET /v1/limits`).

memory_mib integer

disk_gib integer

Disk size; defaults to the template's.

timeout_s integer

Lifetime in seconds from creation (or from the last `POST …/timeout`), capped by your plan.

on_idle string

What happens at `expires_at`. `stop` destroys the sandbox; `pause` pauses it so a later resume (after extending the timeout) continues it.

Enum: stop, pause

env object

Environment variables. Returned as given; put credentials in `secrets`.

secrets object

Environment variables whose values are never returned or logged.

ports object[]

Array of:

port integer REQUIRED

public boolean

Reachable by anyone with the sandbox's long-lived port URL (`ports[].url` in the sandbox; its token lasts 7 days). Private ports (the default) need a URL minted with `POST /v1/sandboxes/{sandbox_id}/ports/{port}/url`.

api object

What code inside the sandbox may call at `http://127.0.0.1:7700`. Empty by default, revoked when the sandbox stops.

scopes string[]

A subset of your own scopes. `*` and `<product>:*` expand to the scopes you hold, except `sandboxes:write`, `vault:*` and `platform:*`, which are granted only when named exactly.

Array of: string

spend_cap_usd number | null

Stop the sandbox's own API calls at this spend. `null` (the default) means the creating principal's cap: a key's own spend cap, or, when code in a sandbox creates this one, that sandbox's grant cap. When the creator has a cap, a higher one here is refused with `403 forbidden`, `reason: scope_escalation`.

connections string[]

Vault connections the sandbox's action calls may use.

Array of: string

egress object

Where sandbox traffic may go, enforced by the node's egress guard. `public` (default): any public internet address. `allowlist`: only hosts matching `allow` (exact hosts or `*.` wildcards). `deny`: no outbound network at all. Private, loopback, tailnet and metadata addresses are always refused. A sandbox has at most 512 outbound connections open and 64 DNS queries in flight at once; past that, new connections are refused (`egress_unavailable`) and queries answered `SERVFAIL`. When the sandbox stops, its outbound connections and its connections to `http://127.0.0.1:7700` close at once.

mode string

Enum: public, allowlist, deny

allow string[]

Array of: string

forkable boolean

Track dirty memory pages so the sandbox can be forked (stretch).

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 sandbox, running.

application/json

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.

400 The request failed validation (`invalid_request`, `invalid_url`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

401 Missing, malformed, expired or revoked credentials (`unauthorized`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

402 The organization has no credits left, or the key reached its spend cap.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

403 The key lacks `sandboxes:write` (`forbidden`, `reason: scope`), or `api` asks for scopes or a spend cap beyond the creator's own (`forbidden`, `reason: scope_escalation`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

404 The template or snapshot does not exist (`template_not_found`, `snapshot_not_found`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

409 The object's state does not allow this operation, or the idempotency key conflicts.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

413 The request body exceeds this operation's limit.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

415 The Content-Type is not accepted by this operation.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

422 The request exceeds a plan limit (`limit_exceeded`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

500 Something failed inside B3OS (`internal`). Retry with backoff.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

502 The agent inside the microVM did not answer (`guest_unreachable`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

curl -X POST 'https://beta-api.b3os.org/v1/sandboxes' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "template": "base",  "snapshot": "string",  "vcpu": 1,  "memory_mib": 512,  "disk_gib": 1,  "timeout_s": 300,  "on_idle": "stop",  "env": {},  "secrets": {},  "ports": [    {      "port": 1,      "public": false    }  ],  "api": {    "scopes": [      "vision:read"    ],    "spend_cap_usd": 0,    "connections": [      "string"    ]  },  "egress": {    "mode": "public",    "allow": [      "string"    ]  },  "forkable": false,  "metadata": {    "customer": "acme",    "ticket": "ENG-1423"  }}'

const response = await fetch('https://beta-api.b3os.org/v1/sandboxes', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "template": "base",    "snapshot": "string",    "vcpu": 1,    "memory_mib": 512,    "disk_gib": 1,    "timeout_s": 300,    "on_idle": "stop",    "env": {},    "secrets": {},    "ports": [      {        "port": 1,        "public": false      }    ],    "api": {      "scopes": [        "vision:read"      ],      "spend_cap_usd": 0,      "connections": [        "string"      ]    },    "egress": {      "mode": "public",      "allow": [        "string"      ]    },    "forkable": false,    "metadata": {      "customer": "acme",      "ticket": "ENG-1423"    }  })});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', headers=headers, json={  "template": "base",  "snapshot": "string",  "vcpu": 1,  "memory_mib": 512,  "disk_gib": 1,  "timeout_s": 300,  "on_idle": "stop",  "env": {},  "secrets": {},  "ports": [    {      "port": 1,      "public": false    }  ],  "api": {    "scopes": [      "vision:read"    ],    "spend_cap_usd": 0,    "connections": [      "string"    ]  },  "egress": {    "mode": "public",    "allow": [      "string"    ]  },  "forkable": false,  "metadata": {    "customer": "acme",    "ticket": "ENG-1423"  }})print(response.json())

201 Response

{  "id": "sbx_01m5t68q1b590rj801nbzsqzkk",  "object": "sandbox",  "status": "running",  "host_id": "sbx-01m5t68q1b590rj801nbzsqzkk",  "template": {    "id": "tpl_01m5t59b2ps0djyzdf082s18bz",    "name": "base"  },  "snapshot": null,  "vcpu": 2,  "memory_mib": 2048,  "disk_gib": 4,  "timeout_s": 900,  "on_idle": "stop",  "expires_at": "2026-10-25T19:15:00.004Z",  "env": {    "PROJECT": "demo"  },  "secret_names": [],  "ports": [    {      "port": 3000,      "public": false,      "url": null    },    {      "port": 8080,      "public": true,      "url": "https://usercontent.b3os.org/sbx/sbx-01m5t68q1b590rj801nbzsqzkk/8080/pt1.n1.1793559600.zijFIOH2DvE3o_MHqQdESQat3b8k_izPyTDLu7qovZd3luYLULkaGmr6X02r7wRO5MmBNCZVzTV8qWsR4wDnBQ/"    }  ],  "api": {    "scopes": [      "vision:run",      "infer:run"    ],    "spend_cap_usd": null,    "connections": []  },  "egress": {    "mode": "public",    "allow": []  },  "forkable": false,  "created_at": "2026-10-25T19:00:00.000Z",  "started_at": "2026-10-25T19:00:00.004Z",  "paused_at": null,  "stopped_at": null,  "stop_reason": null,  "usage": {    "vcpu_ms": 0,    "gib_ms": 0  },  "timing": {    "validate_ms": 0.2,    "claim_ms": 0.01,    "resume_ms": 0.3,    "bind_ms": 1.2,    "total_ms": 1.8  },  "metadata": {}}

400 Response

{  "type": "https://docs.beta.b3os.org/errors#invalid_request",  "title": "Invalid request",  "status": 400,  "code": "invalid_request",  "detail": "1 field failed validation",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "errors": [    {      "pointer": "/url",      "detail": "must be an absolute http or https URL"    }  ]}

401 Response

{  "type": "https://docs.beta.b3os.org/errors#unauthorized",  "title": "Unauthorized",  "status": 401,  "code": "unauthorized",  "detail": "API key checksum does not match; check that the whole key was copied",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "reason": "malformed"}

402 Response

{  "type": "https://docs.beta.b3os.org/errors#credits_exhausted",  "title": "Credits exhausted",  "status": 402,  "code": "credits_exhausted",  "detail": "Organization org_01m5t5hthd29mm5wpza5ndd6mm has no credits left",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

403 Response

{  "type": "https://docs.beta.b3os.org/errors#invalid_request",  "title": "<string>",  "status": 123,  "code": "<string>",  "detail": "<string>",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "errors": [    {      "pointer": "/url",      "detail": "must be an absolute http or https URL"    }  ],  "reason": "<string>",  "required_scope": "<string>",  "retry_after_s": 123,  "limit": {    "id": "vision.scrape.rpm",    "limit": 123,    "unit": "<string>",    "window_s": 123,    "current": 123  },  "current_status": "<string>",  "upstream_status": 123,  "step": "<string>",  "pack_error": {    "code": "<string>",    "message": "<string>",    "retryable": true  }}

404 Response

{  "type": "https://docs.beta.b3os.org/errors#template_not_found",  "title": "Template not found",  "status": 404,  "code": "template_not_found",  "detail": "No template named python-3.13",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

409 Response

{  "type": "https://docs.beta.b3os.org/errors#idempotency_key_conflict",  "title": "Idempotency key conflict",  "status": 409,  "code": "idempotency_key_conflict",  "detail": "This Idempotency-Key was used with a different request body",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

413 Response

{  "type": "https://docs.beta.b3os.org/errors#payload_too_large",  "title": "Payload too large",  "status": 413,  "code": "payload_too_large",  "detail": "Request body is 1572864 bytes; this operation accepts at most 1048576",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

415 Response

{  "type": "https://docs.beta.b3os.org/errors#unsupported_media_type",  "title": "Unsupported media type",  "status": 415,  "code": "unsupported_media_type",  "detail": "Expected Content-Type application/json",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

422 Response

{  "type": "https://docs.beta.b3os.org/errors#limit_exceeded",  "title": "Limit exceeded",  "status": 422,  "code": "limit_exceeded",  "detail": "memory_mib is 4096; sandboxes in this plan allow at most 2048",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "limit": {    "id": "sandboxes.memory_max",    "limit": 2048,    "unit": "MiB"  }}

429 Response

{  "type": "https://docs.beta.b3os.org/errors#rate_limited",  "title": "Rate limited",  "status": 429,  "code": "rate_limited",  "detail": "60 scrapes per minute allowed; retry in 12 seconds",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "retry_after_s": 12,  "limit": {    "id": "vision.scrape.rpm",    "limit": 60,    "unit": "requests",    "window_s": 60,    "current": 60  }}

500 Response

{  "type": "https://docs.beta.b3os.org/errors#internal",  "title": "Internal error",  "status": 500,  "code": "internal",  "detail": "internal error",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

502 Response

{  "type": "https://docs.beta.b3os.org/errors#guest_unreachable",  "title": "Sandbox agent unreachable",  "status": 502,  "code": "guest_unreachable",  "detail": "The guest agent in sbx_01m5t68q1b590rj801nbzsqzkk did not answer within 5000 ms",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

503 Response

{  "type": "https://docs.beta.b3os.org/errors#node_unavailable",  "title": "Node unavailable",  "status": 503,  "code": "node_unavailable",  "detail": "Node n1 is not reachable; retry in 5 seconds",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "retry_after_s": 5}

POST /v1/sandboxes

Base URL

Bearer Token

Headers

Idempotency-Key string

Request Body application/json

Response

Was this page helpful?

Previous List sandboxes

Next Get a sandbox