Create a sandbox

POST

/v1/sandbox/

• Production

Create a new sandbox from a template. The sandbox will start booting immediately. A maximum of 3 sandboxes per organization is enforced.

Authorizations

• BearerAuth

Request Body ^required

object

template_name

required

Name of the template to create the sandbox from.

string

Example

my-template

env_vars

Environment variables to set in the sandbox.

object

key

additional properties

string

vcpu

required

Number of virtual CPUs.

integer

>= 1 <= 8

Example

2

memory_mib

required

Memory in MiB. Must be an even number.

integer format: int64

>= 512 <= 8192

Example

1024

timeout_min

Sandbox timeout in minutes. Defaults to 5 if not provided.

integer format: int64

>= 1 <= 480

Example

10

auto_pause

Automatically pause the sandbox into a snapshot when it reaches its timeout.

boolean

network_policy

Network egress policy for a sandbox. When omitted, defaults to allow-all.

object

mode

required

Policy mode. allow-all permits all egress, deny-all blocks all egress, custom uses the allow/deny lists.

string

Allowed values: allow-all deny-all custom

allow_domains

Domain names to allow outbound access to (custom mode only).

Array<string>

<= 50 items

allow_cidrs

CIDR ranges to allow outbound access to (custom mode only).

Array<string>

<= 10 items

transforms

Per-domain request transforms, such as credential brokering.

Array<object>

<= 20 items

A per-domain request transform rule for credential brokering or header manipulation.

object

domain

required

Domain pattern to match (e.g. api.openai.com).

string

inject_headers

Headers to inject into matching requests.

object

key

additional properties

string

strip_headers

Header names to strip from matching requests.

Array<string>

Responses

201

Sandbox created successfully.

object

id

required

Unique sandbox identifier.

string

Example

sbx-abc123

template_id

required

Template the sandbox was created from.

string

vcpu

required

Number of virtual CPUs assigned to the sandbox.

integer

>= 1

memory_mib

required

Memory assigned to the sandbox, in MiB.

integer format: int64

>= 1

disk_mib

required

Writable disk size assigned to the sandbox, in MiB.

integer format: int64

>= 1

state

required

Current state of the sandbox.

string

Allowed values: starting running snapshotting paused unpausing deleting deleted

auto_pause

required

Whether the sandbox is configured to auto-pause on timeout.

boolean

network_policy

Network egress policy for a sandbox. When omitted, defaults to allow-all.

object

mode

required

Policy mode. allow-all permits all egress, deny-all blocks all egress, custom uses the allow/deny lists.

string

Allowed values: allow-all deny-all custom

allow_domains

Domain names to allow outbound access to (custom mode only).

Array<string>

<= 50 items

allow_cidrs

CIDR ranges to allow outbound access to (custom mode only).

Array<string>

<= 10 items

transforms

Per-domain request transforms, such as credential brokering.

Array<object>

<= 20 items

A per-domain request transform rule for credential brokering or header manipulation.

object

domain

required

Domain pattern to match (e.g. api.openai.com).

string

inject_headers

Headers to inject into matching requests.

object

key

additional properties

string

strip_headers

Header names to strip from matching requests.

Array<string>

created_at

required

ISO 8601 timestamp of when the sandbox was created.

string format: date-time

400

Validation error.

object

message

required

Summary message, e.g. “Invalid request”.

string

errors

required

Array<object>

object

field

required

JSON field name that failed validation (e.g. “path”, “command”).

string

error

required

Human-readable description of the validation failure.

string

401

Unauthorized – invalid or missing API key.

object

message

required

Human-readable error message.

string

409

Conflict – sandbox limit reached.

object

message

required

Human-readable error message.

string