Skip to main content
POST
/
sandboxes
Create Sandbox
curl --request POST \
  --url https://api.declaw.ai/sandboxes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "template": "<string>",
  "timeout": 123,
  "envs": {},
  "metadata": {},
  "network": {
    "allow_out": [
      "<string>"
    ],
    "deny_out": [
      "<string>"
    ],
    "allow_public_traffic": true
  },
  "security": {},
  "lifecycle": {
    "on_timeout": "<string>",
    "auto_resume": true
  }
}
'
{
  "sandbox_id": "<string>",
  "template_id": "<string>",
  "state": "<string>",
  "envd_access_token": "<string>",
  "traffic_access_token": "<string>",
  "guest_ip": "<string>",
  "envd_port": 123,
  "started_at": "<string>"
}
Provisions a new sandbox VM through the orchestrator. The API waits until the VM reports a guest IP address before returning — typically 1–5 seconds. The returned object contains tokens and connection details needed by the SDK.

​
Request Body

​
template
string
Template name to base the sandbox on. Becomes the sandbox name and is prefixed with tpl- for the template_id. Defaults to an empty string (which uses the default base image).Example: "base"
​
timeout
integer
Auto-kill timeout in seconds. When the timeout expires the sandbox state is set to killed and the VM is terminated. Pass 0 to disable auto-kill.Example: 300
​
envs
object
Environment variables to inject into the sandbox VM. Keys and values must be strings.Example: { "OPENAI_API_KEY": "sk-..." }
​
metadata
object
Arbitrary key-value metadata stored with the sandbox. Useful for tagging sandboxes by project, run ID, or agent name.Example: { "project": "my-agent", "run_id": "run-001" }
Resource allocation (vCPUs, memory, disk) is fixed at the template level — the request-level resources field is currently rejected with HTTP 403. Use templates to size sandboxes instead.
​
network
object
Outbound network access controls.
​
security
object
Full SecurityPolicy object (PII config, injection defense, transformation rules, audit config). Passed as a JSON object and stored verbatim. See the Security section for the complete schema.
​
lifecycle
object
Controls what happens when the sandbox timeout fires.

​
Response

Returns a Sandbox object with state running.
​
sandbox_id
string
Unique sandbox identifier. Format: sbx-<8 chars>.
​
template_id
string
Template ID used. Format: tpl-<name>.
​
state
string
Always "running" on a freshly created sandbox.
​
envd_access_token
string
Bearer token for direct envd daemon access. Used internally by the SDK.
​
traffic_access_token
string
Bearer token for the security proxy. Used internally by the SDK.
​
guest_ip
string
Internal IP address of the Firecracker VM.
​
envd_port
integer
Port on which envd listens. Typically 49983.
​
started_at
string
UTC timestamp of sandbox creation.

​
Example

curl -X POST https://api.declaw.ai/sandboxes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base",
    "timeout": 300,
    "envs": { "MY_VAR": "hello" }
  }'
Response
{
  "sandbox_id": "sbx-a1b2c3d4",
  "template_id": "tpl-base",
  "name": "base",
  "state": "running",
  "timeout": 300,
  "envs": { "MY_VAR": "hello" },
  "envd_access_token": "envd-ab12cd34",
  "sandbox_domain": "declaw.dev",
  "traffic_access_token": "traffic-ef56gh78",
  "guest_ip": "172.16.0.5",
  "envd_port": 49983,
  "started_at": "2024-01-15T10:30:00Z",
  "end_at": "2024-01-15T10:35:00Z"
}

​
Error Responses

StatusCause
400Invalid request body or malformed security JSON
401Missing or invalid API key
402Wallet (sandbox or guardrails) has insufficient balance
403Per-sandbox tier limits exceeded (vCPU / memory / disk / session duration), or request-level resources field supplied
429Concurrent sandbox limit reached for your tier, or sandbox create rate limit exceeded
503Orchestrator is unavailable or the VM failed to start