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

# Sandboxes SDK

> Create and manage sandboxes with `rt.sandbox`

`rt.sandbox` is the programmatic way to spin up, drive, and tear down sandboxes. `create()` hands you a live `Sandbox` object you can `exec` against, subscribe to for status and metrics, and pause or destroy when you're done.

## Create

```typescript theme={null}
const sandbox = await rt.sandbox.create({
  name: 'dev-env',
  template: 'base-ubuntu',
  tags: ['docs'],
  resources: { vcpus: 1, memory: '1GB', disk: '10GB' },
  env: { NODE_ENV: 'development' },
  idleTimeout: 600,
  mounts: [{ workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e', path: '/workspace' }],
});

await sandbox.waitForReady();
```

## `SandboxCreateOptions`

| Field          | Type                         | Description                         |
| -------------- | ---------------------------- | ----------------------------------- |
| `name`         | `string`                     | Friendly name                       |
| `template`     | `string`                     | Defaults to `base-ubuntu`           |
| `tags`         | `string[]`                   | Filter and deploy tracking tags     |
| `sshKeys`      | `string[]`                   | SSH key IDs to inject               |
| `rootPassword` | `string`                     | Optional password access            |
| `resources`    | `{ vcpus?, memory?, disk? }` | Resource request                    |
| `env`          | `Record<string,string>`      | Environment variables               |
| `idleTimeout`  | `number`                     | Idle timeout in seconds             |
| `mounts`       | `{ workspaceId, path }[]`    | Workspace mounts under `/workspace` |

Workspace mount paths must be `/workspace` or a subpath under `/workspace`. When an agent uses this sandbox, the mounted workspace is persistent filesystem state the agent can carry across runs.

## List

```typescript theme={null}
const all = await rt.sandbox.list();
const running = await rt.sandbox.list({ status: 'running', limit: 20 });

const page = await rt.sandbox.listPage({
  status: 'running',
  limit: 20,
});
```

Filters include `status`, `tags`, `template`, `exclude_template`, `limit`, `cursor`, and admin-only `all`.

## Get an Instance

```typescript theme={null}
const sandbox = rt.sandbox.get('sandbox-abc123');
```

`get()` returns a local `Sandbox` object. It does not fetch immediately; methods and subscriptions use the API.

## Execute

```typescript theme={null}
const result = await sandbox.exec('npm test', {
  cwd: '/workspace',
  timeout: 120000,
  env: { CI: 'true' },
});

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);
```

## Lifecycle

```typescript theme={null}
await sandbox.pause();
await sandbox.resume();
await sandbox.destroy();

await rt.sandbox.destroy('sandbox-abc123');
```

## Dev URLs, SSH, and logs

These live on the manager and take a sandbox id:

```typescript theme={null}
// Capability-protected URL for a port (wakes a paused sandbox).
const { url } = await rt.sandbox.getUrl('sandbox-abc123', 3000);

// Connection details for SSH / the browser desktop.
const ssh = await rt.sandbox.ssh('sandbox-abc123');
const vnc = await rt.sandbox.vnc('sandbox-abc123');     // desktop templates; URL is normalized

// Logs, point-in-time metrics, activity, and metadata updates.
const { entries } = await rt.sandbox.logs('sandbox-abc123', { tail: 100 });
const metrics = await rt.sandbox.stats('sandbox-abc123');
const { events } = await rt.sandbox.activity('sandbox-abc123', { limit: 50 });
await rt.sandbox.update('sandbox-abc123', { name: 'renamed', tags: ['ci'] });
```

## Wait and Subscribe

```typescript theme={null}
await sandbox.waitForReady(120000);

const offStatus = sandbox.on('status', (state) => {
  console.log(state.status, state.sshReady, state.vncReady);
});

const offMetrics = sandbox.on('metrics', (metrics) => {
  console.log(metrics.cpuPercent, metrics.memUsedPercent);
});

offStatus();
offMetrics();
await sandbox.close();
```

## Accessors

| Property           | Description                           |
| ------------------ | ------------------------------------- |
| `sandbox.id`       | Sandbox ID                            |
| `sandbox.status`   | Current known status or `unknown`     |
| `sandbox.sshReady` | Current known SSH readiness           |
| `sandbox.vncReady` | Current known VNC readiness           |
| `sandbox.vncUrl`   | Normalized desktop URL when available |
| `sandbox.state`    | Last full state payload or `null`     |
| `sandbox.metrics`  | Last metrics payload or `null`        |

## Not In The SDK

Named checkpoint and restore operations are not public SDK methods. Use pause/resume for lifecycle preservation.