Skip to main content
POST
/
v1
/
sandboxes
curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base-ubuntu",
    "name": "build-runner",
    "tags": ["ci"],
    "resources": {
      "vcpus": 2,
      "memory": "4GB"
    },
    "mounts": [
      {
        "workspaceId": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
        "path": "/workspace"
      }
    ],
    "env": {
      "NODE_ENV": "development"
    }
  }'

{
  "data": {
    "id": "sandbox-abc123",
    "template": "base-ubuntu",
    "resources": {
      "vcpus": 2,
      "memory": "4GB",
      "disk": "10GB"
    },
    "status": "creating",
    "sshReady": false,
    "vncReady": false,
    "createdAt": "2026-05-06T10:00:00Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Request Body

​
template
string
required
Template slug. Current public templates include base-ubuntu and desktop-ubuntu.
​
name
string
Optional human-readable name. GET /v1/sandboxes/{id} accepts either sandbox ID or name.
​
tags
array
Optional tags for filtering sandbox lists.
​
sshKeys
array
SSH public keys or registered SSH key identifiers to authorize.
​
rootPassword
string
Optional root password for access flows that require it.
​
resources
object
Resource request.
​
env
object
Environment variables made available to sandbox processes.
​
idleTimeout
number
Seconds of inactivity before auto-pause. Omit to use the platform default.
​
mounts
array
Workspace mounts. Each mount includes workspaceId and guest path. Paths must be /workspace or a subpath under /workspace.
​
metadata
object
Optional metadata for direct API callers.
​
projectId
string
Optional project assignment.

​
Response

​
id
string
Sandbox identifier.
​
status
string
Initial status, usually pending or creating.
​
template
string
Template used to create the sandbox.
​
resources
object
Resource allocation.
​
sshReady
boolean
Whether SSH is ready.
​
vncReady
boolean
Whether browser desktop access is ready for desktop templates.
curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base-ubuntu",
    "name": "build-runner",
    "tags": ["ci"],
    "resources": {
      "vcpus": 2,
      "memory": "4GB"
    },
    "mounts": [
      {
        "workspaceId": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
        "path": "/workspace"
      }
    ],
    "env": {
      "NODE_ENV": "development"
    }
  }'

{
  "data": {
    "id": "sandbox-abc123",
    "template": "base-ubuntu",
    "resources": {
      "vcpus": 2,
      "memory": "4GB",
      "disk": "10GB"
    },
    "status": "creating",
    "sshReady": false,
    "vncReady": false,
    "createdAt": "2026-05-06T10:00:00Z"
  }
}

​
Notes

  • Create returns as soon as the sandbox has been requested. Poll GET /v1/sandboxes/{id} or use sandbox.waitForReady() in the SDK.
  • Use desktop-ubuntu when you need browser desktop access.
  • Use workspace mounts for files that should persist across sandbox-backed agent runs.
  • Named checkpoint and restore operations are not part of the public sandbox API. Use pause/resume for lifecycle preservation.