---
title: "Create a sandbox"
method: POST
path: "/sandboxes"
tags: ["Sandboxes"]
---

# Create a sandbox

`POST /sandboxes`

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`.

## Request body

- CreateSandboxInput
  - `name` string — Display name. Auto-generated (random animal) if omitted.
  - `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.
  - `environmentId` string — Project-environment ObjectId to scope the sandbox to.
  - `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` SandboxSpecs
    - `cpu` integer — CPU shares in Nomad MHz units.
    - `memory` integer — Memory in MB.
    - `disk` integer — Ephemeral scratch disk in GB. Separate from persistent storage.
  - `autoDestroy` boolean — If true, sandbox auto-destroys after `destroyTimeout`.
  - `destroyTimeout` '30m' | '1h' | '3h' | '6h' | '12h' | '18h' — Required when `autoDestroy=true`. Ignored otherwise.
  - `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` SandboxEgressConfig — Outbound network policy applied to the sandbox container.
    - `mode` 'open' | 'restricted' | 'deny_all', required — Outbound network policy for a sandbox. - `open` — full outbound internet access (default). - `deny_all` — all outbound connections blocked; inbound Brimble API calls still work. - `restricted` — default deny with an allowlist (`allow` required on update).
    - `allow` string[] — Allowlist for `restricted` mode. Each entry is an IPv4 address, CIDR range (e.g. `10.0.0.0/8`), or hostname (e.g. `api.example.com`). Required with at least one entry when updating to `restricted`; optional at create time.
  - `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`.
  - `volumeId` string — Attach an existing detached volume. Mutually exclusive with `persistent` / `persistentDiskGB`.
  - `fromSnapshot` string — Restore from a snapshot you own; replaces the template image.
  - `snapshotMode` 'manual' | 'automatic'
  - `snapshotFrequency` string — 5-field cron expression (e.g. `0 */2 * * *`). Required when `snapshotMode=automatic`, forbidden otherwise.

## Response `201`

Sandbox provisioned and ready

- CreateSandboxEnvelope
  - `message` string, required
  - `data` CreateSandboxResult, required
    - `id` string, required
    - `name` string, required
    - `template` string, required
    - `status` 'starting' | 'ready' | 'pausing' | 'paused' | 'resuming' | 'failed' | 'destroyed', required
    - `created_at` string, date-time, required
    - `expires_at` string, date-time, required

## Other responses

- `400` — Validation error / invalid state transition
- `403` — Plan / spending-limit / permission error
- `404` — Sandbox or related resource not found (also returned when owned by another user)
- `503` — Provisioning failed (cluster full, placement failure, etc.)

---

[API](https://skmtc.net/brimblehq/apis/brimble-sandbox-api.md) · [All operations](https://skmtc.net/brimblehq/apis/brimble-sandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brimblehq/brimble-sandbox-api/versions/7fe2df041597/schema)