Sandboxes
Create, list, inspect, and kill sandboxes — isolated live execution environments.
A sandbox is an isolated live execution environment. You create one from a template, run commands and work with files inside it, and it's destroyed when its TTL expires or when you kill it.
The Sandbox object
| Field | Type | Description |
|---|---|---|
id | string | Sandbox ID, prefixed sbx_ |
orgId | string | Owning organization, prefixed org_ |
projectId | string | Owning project, prefixed prj_ |
status | string | creating, starting, ready, running, idle, expiring, destroyed, or failed |
templateId | string | Template ID, prefixed tpl_ |
templateSlug | string | Template slug, such as python |
templateVersion | string | Resolved template version |
templateVersionId | string | TemplateVersion ID, prefixed tplv_ |
ttlMs | integer | Requested lifetime in milliseconds |
expiresAt | string | ISO 8601 timestamp when the sandbox expires |
metadata | object | String labels set at creation |
createdAt | string | ISO 8601 creation timestamp, when available |
destroyedAt | string | ISO 8601 destruction timestamp, once destroyed |
destroyedReason | string | idle_expired, platform_cleanup, ttl_expired, or user_killed |
Create a sandbox
POST /v1/sandboxes — requires scope sandbox:create. Accepts an
Idempotency-Key header.
Creates a sandbox from a template and returns it once provisioning starts. All body fields are optional:
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
projectId | string | No | Default project | A prj_ ID your key can access |
template | string | No | — | python, node, python-node, or base |
templateVersionId | string | No | — | A tplv_ ID; pins an exact immutable environment |
ttlMs | integer | No | 3600000 | Positive integer, max 3600000 (limits depend on plan and may change) |
metadata | object | No | — | String map; max 16 keys, keys ≤ 64 chars, values ≤ 512 chars, ≤ 4 KB total |
curl -X POST https://api.crownest.dev/v1/sandboxes \
-H "Authorization: Bearer $CROWNEST_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7f3d9c2a-create-01" \
-d '{
"template": "python",
"ttlMs": 1800000,
"metadata": { "run": "nightly-eval" }
}'Returns 201 with the created sandbox:
{
"sandbox": {
"id": "sbx_abc123",
"orgId": "org_abc123",
"projectId": "prj_abc123",
"status": "creating",
"templateId": "tpl_abc123",
"templateSlug": "python",
"templateVersion": "1.0.0",
"templateVersionId": "tplv_abc123",
"ttlMs": 1800000,
"expiresAt": "2026-06-11T13:30:00.000Z",
"metadata": { "run": "nightly-eval" },
"createdAt": "2026-06-11T13:00:00.000Z"
}
}Errors: invalid_request, forbidden, not_found, quota_exceeded,
sandbox_ttl_exceeded.
List sandboxes
GET /v1/sandboxes — requires scope sandbox:read.
Returns a paginated list of live sandboxes, newest first. Destroyed and failed sandboxes are excluded unless you ask for them:
| Parameter | Type | Description |
|---|---|---|
projectId | string | Filter to one project |
status | string | Filter by sandbox status |
include | string | historical to include destroyed and failed sandboxes |
limit | integer | Page size, default 50, max 100 |
cursor | string | Pagination cursor |
curl "https://api.crownest.dev/v1/sandboxes?include=historical&limit=10" \
-H "Authorization: Bearer $CROWNEST_API_KEY"{
"data": [
{
"id": "sbx_abc123",
"status": "ready",
"templateSlug": "python",
"expiresAt": "2026-06-11T13:30:00.000Z"
}
],
"hasMore": false
}Get a sandbox
GET /v1/sandboxes/{sandboxId} — requires scope sandbox:read.
Returns one sandbox by ID. Poll this endpoint to watch status move from
creating to ready.
curl https://api.crownest.dev/v1/sandboxes/sbx_abc123 \
-H "Authorization: Bearer $CROWNEST_API_KEY"Returns 200 with { "sandbox": { ... } }. Errors: forbidden,
not_found.
Kill a sandbox
DELETE /v1/sandboxes/{sandboxId} — requires scope sandbox:kill.
Destroys the sandbox immediately. The workspace filesystem is lost; only artifacts you exported survive. The operation is idempotent by state — deleting an already-destroyed sandbox returns the destroyed record rather than an error.
curl -X DELETE https://api.crownest.dev/v1/sandboxes/sbx_abc123 \
-H "Authorization: Bearer $CROWNEST_API_KEY"{
"sandbox": {
"id": "sbx_abc123",
"status": "destroyed",
"destroyedAt": "2026-06-11T13:05:00.000Z",
"destroyedReason": "user_killed"
}
}Errors: forbidden, not_found.