> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> TypeScript Sandbox class: create, connect, list, kill, set timeout, pause, snapshot, and retrieve metrics.

```typescript theme={null}
import { Sandbox } from '@declaw/sdk';
import type { SandboxOpts, SandboxInfo, SandboxMetrics, SnapshotInfo } from '@declaw/sdk';
```

`Sandbox` is the main entry point in the TypeScript SDK. All methods are async and return Promises. The constructor is private — use `Sandbox.create()` or `Sandbox.connect()`.

## Static methods

### `Sandbox.create()`

Create a new sandbox and return a connected `Sandbox` instance.

```typescript theme={null}
const sbx = await Sandbox.create({
  template: 'base',
  timeout: 300,
  envs: { MY_VAR: 'hello' },
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});
```

<ParamField body="opts" type="SandboxOpts">
  Optional sandbox creation options. All fields are optional. See
  [SandboxOpts](/sdks/typescript/overview#sandboxopts) for the full
  parameter list.
</ParamField>

**Returns** `Promise<Sandbox>`

***

### `Sandbox.connect()`

Connect to an existing sandbox by ID.

```typescript theme={null}
const sbx = await Sandbox.connect('sandbox-id-here', {
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});
```

<ParamField body="sandboxId" type="string" required>
  The sandbox ID to connect to. Must be alphanumeric with hyphens/underscores.
</ParamField>

<ParamField body="opts" type="object">
  Optional: `apiKey`, `domain`, `apiUrl`, `requestTimeout`.
</ParamField>

**Returns** `Promise<Sandbox>`

***

### `Sandbox.list()`

List sandboxes with optional filtering and pagination.

```typescript theme={null}
const { sandboxes, nextToken } = await Sandbox.list({
  limit: 20,
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});
```

<ParamField body="opts.query" type="Record<string, string>">
  Filter query parameters passed directly to the API.
</ParamField>

<ParamField body="opts.limit" type="number">
  Maximum number of sandboxes to return.
</ParamField>

<ParamField body="opts.nextToken" type="string">
  Pagination cursor from a previous `list()` call.
</ParamField>

<ParamField body="opts.apiKey" type="string">
  API key override.
</ParamField>

<ParamField body="opts.domain" type="string">
  Domain override.
</ParamField>

<ParamField body="opts.requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<{ sandboxes: SandboxInfo[]; nextToken?: string }>`

***

## Instance methods

### `sbx.kill()`

Kill and destroy the sandbox. The sandbox ID becomes invalid after this call.

```typescript theme={null}
const killed = await sbx.kill();
console.log(killed); // true
```

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<boolean>` — `true` if killed, `false` if already dead.

***

### `sbx.isRunning()`

Check whether the sandbox is currently running.

```typescript theme={null}
const running = await sbx.isRunning();
```

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<boolean>`

***

### `sbx.setTimeout()`

Update the sandbox timeout.

```typescript theme={null}
await sbx.setTimeout(600); // extend to 10 minutes from now
```

<ParamField body="timeout" type="number" required>
  New timeout in seconds.
</ParamField>

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<void>`

***

### `sbx.getInfo()`

Fetch current metadata and state of the sandbox.

```typescript theme={null}
const info = await sbx.getInfo();
console.log(info.state);     // SandboxState.Running
console.log(info.startedAt); // Date
```

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<SandboxInfo>`

***

### `sbx.getMetrics()`

Retrieve CPU, memory, and disk usage metrics.

```typescript theme={null}
const metrics = await sbx.getMetrics({
  start: new Date(Date.now() - 5 * 60 * 1000),
  end: new Date(),
});
for (const m of metrics) {
  console.log(m.cpuUsagePercent, m.memoryUsageMb);
}
```

<ParamField body="opts.start" type="Date">
  Start of time range.
</ParamField>

<ParamField body="opts.end" type="Date">
  End of time range.
</ParamField>

<ParamField body="opts.requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<SandboxMetrics[]>`

***

### `sbx.pause()`

Pause the sandbox.

```typescript theme={null}
await sbx.pause();
```

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<void>`

***

### `sbx.createSnapshot()`

Create a snapshot of the sandbox.

```typescript theme={null}
const snap = await sbx.createSnapshot();
console.log(snap.snapshotId);
```

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

**Returns** `Promise<SnapshotInfo>`

***

### `sbx.getHost()`

Return the URL that reverse-proxies HTTP traffic to the given port inside the sandbox. Requires `allowPublicTraffic` to be enabled in the sandbox's network config (the default).

```typescript theme={null}
const url = sbx.getHost(8080);
// https://api.declaw.ai/sandboxes/sbx-.../ports/8080
```

<ParamField body="port" type="number" required>
  The port number to proxy to inside the sandbox.
</ParamField>

**Returns** `string`

***

### `sbx.getMcpUrl()`

Return the URL for an MCP server listening on port 50005 inside the sandbox. Equivalent to `sbx.getHost(50005) + "/mcp"`.

```typescript theme={null}
const url = sbx.getMcpUrl();
// https://api.declaw.ai/sandboxes/sbx-.../ports/50005/mcp
```

**Returns** `string`

***

### `sbx.close()`

Close the underlying HTTP client and release resources. Does not kill the sandbox.

```typescript theme={null}
sbx.close();
```

**Returns** `void`

***

## Properties

| Property                 | Type                  | Description                              |
| ------------------------ | --------------------- | ---------------------------------------- |
| `sbx.sandboxId`          | `string`              | Unique sandbox identifier.               |
| `sbx.config`             | `ConnectionConfig`    | Connection config used by this instance. |
| `sbx.envdAccessToken`    | `string \| undefined` | Access token for the in-VM envd service. |
| `sbx.sandboxDomain`      | `string \| undefined` | Domain where the sandbox is accessible.  |
| `sbx.trafficAccessToken` | `string \| undefined` | Token for traffic routing.               |
| `sbx.commands`           | `Commands`            | Commands sub-module.                     |
| `sbx.files`              | `Filesystem`          | Filesystem sub-module.                   |
| `sbx.pty`                | `Pty`                 | PTY sub-module.                          |

***

## Automatic disposal

`Sandbox` implements `Symbol.asyncDispose`, so you can use the `await using` syntax from TypeScript 5.2+ for automatic cleanup:

```typescript theme={null}
await using sbx = await Sandbox.create({ apiKey: 'key', domain: 'host:8080' });
const result = await sbx.commands.run('node --version');
console.log(result.stdout);
await sbx.kill(); // still need to explicitly kill
// sbx.close() is called automatically here
```

***

## Data models

### `SandboxInfo`

```typescript theme={null}
interface SandboxInfo {
  sandboxId: string;
  templateId: string;
  name: string;
  metadata: Record<string, string>;
  startedAt?: Date;
  endAt?: Date;
  state: SandboxState;
}
```

### `SandboxState`

```typescript theme={null}
enum SandboxState {
  Running  = 'running',
  Paused   = 'paused',
  Creating = 'creating',
  Killed   = 'killed',
}
```

### `SandboxMetrics`

```typescript theme={null}
interface SandboxMetrics {
  timestamp: Date;
  cpuUsagePercent: number;
  memoryUsageMb: number;
  diskUsageMb: number;
}
```

### `SandboxLifecycle`

```typescript theme={null}
interface SandboxLifecycle {
  onTimeout: string;    // "kill" or "pause"
  autoResume: boolean;
}
```

### `SnapshotInfo`

```typescript theme={null}
interface SnapshotInfo {
  snapshotId: string;
  sandboxId: string;
  createdAt?: Date;
}
```

### `SandboxQuery`

```typescript theme={null}
interface SandboxQuery {
  metadata?: Record<string, string>;
  state?: SandboxState[];
}
```