Sandboxes API

Create sandboxes, execute commands, manage files, and destroy runtime instances through the StacyVM REST API.

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

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

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.

Related

• Quickstart
• Full REST API reference
• Core concepts