> ## 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.

# Create Sandbox

> Create a long-lived Linux or desktop sandbox

## Request Body

<ParamField body="template" type="string" required>
  Template slug. Current public templates include `base-ubuntu` and `desktop-ubuntu`.
</ParamField>

<ParamField body="name" type="string">
  Optional human-readable name. `GET /v1/sandboxes/{id}` accepts either sandbox ID or name.
</ParamField>

<ParamField body="tags" type="array">
  Optional tags for filtering sandbox lists.
</ParamField>

<ParamField body="sshKeys" type="array">
  SSH public keys or registered SSH key identifiers to authorize.
</ParamField>

<ParamField body="rootPassword" type="string">
  Optional root password for access flows that require it.
</ParamField>

<ParamField body="resources" type="object">
  Resource request.

  <Expandable title="resources properties">
    <ParamField body="resources.vcpus" type="number">
      CPU count.
    </ParamField>

    <ParamField body="resources.memory" type="string">
      Memory, such as `1GB` or `4GB`.
    </ParamField>

    <ParamField body="resources.disk" type="string">
      Disk size, such as `10GB`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="env" type="object">
  Environment variables made available to sandbox processes.
</ParamField>

<ParamField body="idleTimeout" type="number">
  Seconds of inactivity before auto-pause. Omit to use the platform default.
</ParamField>

<ParamField body="mounts" type="array">
  Workspace mounts. Each mount includes `workspaceId` and guest `path`. Paths must be `/workspace` or a subpath under `/workspace`.

  <Expandable title="mounts item properties">
    <ParamField body="mounts[].workspaceId" type="string" required>
      Organization workspace ID.
    </ParamField>

    <ParamField body="mounts[].path" type="string" required>
      Mount target inside the sandbox, such as `/workspace` or `/workspace/data`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Optional metadata for direct API callers.
</ParamField>

<ParamField body="projectId" type="string">
  Optional project assignment.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Sandbox identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status, usually `pending` or `creating`.
</ResponseField>

<ResponseField name="template" type="string">
  Template used to create the sandbox.
</ResponseField>

<ResponseField name="resources" type="object">
  Resource allocation.
</ResponseField>

<ResponseField name="sshReady" type="boolean">
  Whether SSH is ready.
</ResponseField>

<ResponseField name="vncReady" type="boolean">
  Whether browser desktop access is ready for desktop templates.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```typescript SDK theme={null}
  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();
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## 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.