Create Sandbox - Runtools.ai

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"
    }
  }'

const sandbox = await rt.sandbox.create({
  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',
  },
});

await sandbox.waitForReady();

{
  "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"
  }
}

POST

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"
    }
  }'

const sandbox = await rt.sandbox.create({
  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',
  },
});

await sandbox.waitForReady();

{
  "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"
  }
}

Request Body

string

required

Template slug. Current public templates include base-ubuntu and desktop-ubuntu.

string

Optional human-readable name. GET /v1/sandboxes/{id} accepts either sandbox ID or name.

array

Optional tags for filtering sandbox lists.

array

SSH public keys or registered SSH key identifiers to authorize.

string

Optional root password for access flows that require it.

object

Resource request.

Show resources properties

number

CPU count.

string

Memory, such as 1GB or 4GB.

string

Disk size, such as 10GB.

object

Environment variables made available to sandbox processes.

number

Seconds of inactivity before auto-pause. Omit to use the platform default.

array

Workspace mounts. Each mount includes workspaceId and guest path. Paths must be /workspace or a subpath under /workspace.

Show mounts item properties

string

required

Organization workspace ID.

string

required

Mount target inside the sandbox, such as /workspace or /workspace/data.

object

Optional metadata for direct API callers.

string

Optional project assignment.

Response

string

Sandbox identifier.

string

Initial status, usually pending or creating.

string

Template used to create the sandbox.

object

Resource allocation.

boolean

Whether SSH is ready.

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"
    }
  }'

const sandbox = await rt.sandbox.create({
  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',
  },
});

await sandbox.waitForReady();

{
  "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.

​Request Body

​Response

​Notes

Request Body

Response

Notes