Skip to main content
Use the sandboxes API when you want direct HTTP access or when you are building your own SDK.

​
Prerequisites

  • A running StacyVM server.
  • X-API-Key when auth is enabled.
  • X-User-ID when you want explicit tenant attribution.

​
Create A Sandbox

curl -sS -X POST http://localhost:7423/api/v1/sandboxes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "X-User-ID: user_123" \
  -d '{
    "image": "python:3.12",
    "provider": "docker",
    "memory_mb": 512,
    "vcpus": 1,
    "ttl": "10m",
    "metadata": {"purpose": "quickstart"}
  }'
​
image
string
Runtime image to start, such as python:3.12 for Docker.
​
provider
string
Provider override. Omit this to use the server default.
​
memory_mb
integer
Requested memory limit in megabytes.
​
vcpus
integer
Requested virtual CPU count.
​
ttl
string
Auto-destroy duration using Go duration syntax, such as 10m or 1h30m.
​
metadata
object
String key-value labels stored with the sandbox.

​
Success Response

{
  "id": "sb_a1b2c3d4",
  "state": "running",
  "provider": "docker",
  "image": "python:3.12",
  "memory_mb": 512,
  "vcpus": 1,
  "created_at": "2026-05-10T10:00:00Z",
  "expires_at": "2026-05-10T10:10:00Z",
  "metadata": {
    "purpose": "quickstart"
  }
}
​
id
string
Unique sandbox ID used by exec, file, preview, and destroy endpoints.
​
state
string
Current lifecycle state, usually running after a successful create.
​
expires_at
string
UTC timestamp when TTL cleanup should destroy the sandbox.

​
Execute A Command

curl -sS -X POST http://localhost:7423/api/v1/sandboxes/sb_a1b2c3d4/exec \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -d '{"command":"python3 -c \"print(40 + 2)\"","timeout":"10s"}'

​
Common Error

{
  "code": "not_found",
  "message": "sandbox sb_a1b2c3d4 not found"
}
The most common causes are an expired TTL, a sandbox that was already destroyed, or an ID from another environment.

​
Destroy A Sandbox

curl -sS -X DELETE http://localhost:7423/api/v1/sandboxes/sb_a1b2c3d4 \
  -H "X-API-Key: sk_test_YOUR_API_KEY"
Destroy is idempotent. It is safe to call during cleanup even if TTL cleanup already ran.