Skip to main content
POST
/
v1
/
sandboxes
curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "nodejs-20",
    "mounts": [
      { "workspaceId": "my-project", "path": "/workspace" }
    ],
    "idleTimeout": 600,
    "resources": {
      "vcpus": 2,
      "memory": "4GB"
    },
    "env": {
      "NODE_ENV": "development"
    }
  }'

{
  "data": {
    "id": "sandbox-abc123",
    "status": "creating",
    "template": "nodejs-20",
    "resources": {
      "vcpus": 2,
      "memory": "4GB",
      "disk": "10GB"
    },
    "createdAt": "2025-01-21T10:00:00Z"
  }
}

​
Request

​
template
string
required
Template to use. Either a system template (e.g., nodejs-20) or your custom template slug.
​
mounts
array
Persistent storage mounts. Each mount has workspaceId (your identifier) and path (mount location).
​
idleTimeout
number
default:"600"
Seconds of inactivity before auto-pausing (default: 10 minutes). Set to 0 to disable auto-pause.
​
resources
object
Resource limits for the sandbox.
​
env
object
Environment variables to set in the sandbox.
​
metadata
object
Custom metadata to attach to the sandbox.

​
Response

​
id
string
Unique sandbox identifier (e.g., sandbox-abc123)
​
status
string
Current status: creating, running, paused, stopped
​
template
string
Template used to create the sandbox
​
createdAt
string
ISO 8601 timestamp
​
resources
object
Resource allocation
curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "nodejs-20",
    "mounts": [
      { "workspaceId": "my-project", "path": "/workspace" }
    ],
    "idleTimeout": 600,
    "resources": {
      "vcpus": 2,
      "memory": "4GB"
    },
    "env": {
      "NODE_ENV": "development"
    }
  }'

{
  "data": {
    "id": "sandbox-abc123",
    "status": "creating",
    "template": "nodejs-20",
    "resources": {
      "vcpus": 2,
      "memory": "4GB",
      "disk": "10GB"
    },
    "createdAt": "2025-01-21T10:00:00Z"
  }
}

​
Notes

  • The sandbox starts in creating status and transitions to running within ~2 seconds.
  • Use Get Sandbox to check status.
  • Billing starts when status is running.