Sandboxes

Create a sandbox

Provisions a sandbox synchronously. The request blocks until the sandbox is ready (~2–3s typical). Returns 201 with status: "ready". Use a client timeout of at least 90 seconds. On provisioning failure the API returns 503.

GET /sandboxes/{id}/wait remains for reconnect edge cases (e.g. after resume); it is not required after create.

Network egress

Control outbound network access at create time with the egress object, or the legacy blockOutbound: true shorthand (maps to deny_all). You cannot set both on the same request.

`egress.mode`	Behavior
`open`	Full outbound internet (default when omitted)
`deny_all`	All outbound connections blocked
`restricted`	Default deny + allowlist in `egress.allow`

Change policy later with PUT /sandboxes/{id}/egress.

POST

sandboxes

curl --request POST \
  --url https://sandbox.brimble.io/sandboxes \
  --header 'Content-Type: application/json' \
  --header 'x-brimble-key: <api-key>' \
  --data '
{
  "template": "node-22",
  "region": "auto"
}
'

{
  "message": "Sandbox created",
  "data": {
    "id": "<string>",
    "name": "<string>",
    "template": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

Provisions a sandbox synchronously. The request blocks until the sandbox is ready (~2–3s on a typical cold start). Use a client timeout of at least 90 seconds. On failure the API returns 503 with an actionable message.

Network egress (request body)

Control outbound network access when creating a sandbox:

Field	Type	Description
`egress.mode`	`"open"` \| `"restricted"` \| `"deny_all"`	Outbound policy. Defaults to `open` when omitted.
`egress.allow`	`string[]`	Allowlist for `restricted` mode: IPv4, CIDR, or hostname. Up to 50 entries.
`blockOutbound`	`boolean`	Legacy shorthand for `deny_all`. Cannot be combined with `egress`.

Examples

{
  "template": "node-22",
  "region": "auto",
  "egress": {
    "mode": "restricted",
    "allow": ["1.1.1.1", "api.example.com"]
  }
}

{
  "template": "python-3.12",
  "egress": { "mode": "deny_all" }
}

The create response does not include egress; fetch the sandbox with GET /sandboxes/{id} to read the applied policy. Change egress on a running sandbox with Update sandbox egress.

Authorizations

x-brimble-key

string

header

required

Your account-level Brimble API key. Find it in the dashboard under your profile drawer → API key (click the avatar in the sidebar). Available on paid plans only.

Body

application/json

name

string

Display name. Auto-generated (random animal) if omitted.

Required string length: 1 - 64

template

string

Template name from the available sandbox images (e.g. node-22, python-3.12). Defaults to the server's configured default.

teamId

string

Create the sandbox under a team you're a member of. Copy the team ID from the team's settings page in the dashboard. Omit for a personal sandbox.

Pattern: ^[a-f0-9]{24}$

environmentId

string

Project-environment ObjectId to scope the sandbox to.

Pattern: ^[a-f0-9]{24}$

region

string

Region id from GET /v1/regions, or "auto" to let the server pick one for you. Optional; defaults to "auto" when omitted.

specs

object

Show child attributes

autoDestroy

boolean

If true, sandbox auto-destroys after destroyTimeout.

destroyTimeout

enum<string>

Required when autoDestroy=true. Ignored otherwise.

Available options:

30m,

1h,

3h,

6h,

12h,

18h

oneShot

boolean

If true, sandbox auto-destroys when its main process exits.

blockOutbound

boolean

Legacy shorthand for egress.mode = deny_all. Prefer egress for new integrations. Cannot be combined with egress on the same request.

egress

object

Outbound network policy applied to the sandbox container.

Show child attributes

Example:

{
  "mode": "restricted",
  "allow": ["1.1.1.1", "api.example.com"]
}

persistent

boolean

Provision a fresh per-sandbox persistent volume for the sandbox's workspace directory.

persistentDiskGB

integer

Required when persistent=true. Mutually exclusive with volumeId.

Required range: 10 <= x <= 50

volumeId

string

Attach an existing detached volume. Mutually exclusive with persistent / persistentDiskGB.

Pattern: ^[a-f0-9]{24}$

fromSnapshot

string

Restore from a snapshot you own; replaces the template image.

Pattern: ^[a-f0-9]{24}$

snapshotMode

enum<string>

default:manual

Available options:

manual,

automatic

snapshotFrequency

string

5-field cron expression (e.g. 0 */2 * * *). Required when snapshotMode=automatic, forbidden otherwise.

Response

Sandbox provisioned and ready

message

string

required

Example:

"Sandbox created"

data

object

required

Show child attributes

Last modified on July 1, 2026

List sandboxesReturns sandboxes owned by the caller, sorted by `created_at` descending.

curl --request POST \
  --url https://sandbox.brimble.io/sandboxes \
  --header 'Content-Type: application/json' \
  --header 'x-brimble-key: <api-key>' \
  --data '
{
  "template": "node-22",
  "region": "auto"
}
'

{
  "message": "Sandbox created",
  "data": {
    "id": "<string>",
    "name": "<string>",
    "template": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

Discovery

Sandboxes

Runtime

Observability

Snapshots

Volumes

Sandboxes

Snapshots

Observability

Runtime

Volumes

Create a sandbox

Network egress

Network egress (request body)

Examples

Authorizations

Body

Response

​Network egress (request body)

​Examples

Authorizations

Body

Response

Network egress (request body)

Examples