Skip to main content
POST
/
sandboxes
Create a sandbox
curl --request POST \
  --url https://sandbox.brimble.io/sandboxes \
  --header 'Content-Type: application/json' \
  --header 'x-brimble-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "template": "<string>",
  "teamId": "<string>",
  "environmentId": "<string>",
  "region": "<string>",
  "specs": {
    "cpu": 1000,
    "memory": 1024,
    "disk": 3
  },
  "autoDestroy": true,
  "oneShot": true,
  "blockOutbound": true,
  "persistent": true,
  "persistentDiskGB": 30,
  "volumeId": "<string>",
  "fromSnapshot": "<string>",
  "snapshotMode": "manual",
  "snapshotFrequency": "<string>"
}
'
{
  "message": "Sandbox creation started",
  "data": {
    "id": "<string>",
    "name": "<string>",
    "template": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

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
​
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

If true, outbound network traffic from the sandbox is denied.

​
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 provisioning queued

​
message
string
required
Example:

"Sandbox creation started"

​
data
object
required
Last modified on May 23, 2026