Sandbox

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.

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

SandboxOpts

Optional sandbox creation options. All fields are optional. See SandboxOpts for the full parameter list.

Returns Promise<Sandbox>

`Sandbox.connect()`

Connect to an existing sandbox by ID.

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

string

required

The sandbox ID to connect to. Must be alphanumeric with hyphens/underscores.

object

Optional: apiKey, domain, apiUrl, requestTimeout.

Returns Promise<Sandbox>

`Sandbox.list()`

List sandboxes with optional filtering and pagination.

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

Record<string, string>

Filter query parameters passed directly to the API.

number

Maximum number of sandboxes to return.

string

Pagination cursor from a previous list() call.

string

API key override.

string

Domain override.

number

Per-request HTTP timeout in milliseconds.

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

Instance methods

`sbx.kill()`

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

const killed = await sbx.kill();
console.log(killed); // true

number

Per-request HTTP timeout in milliseconds.

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

`sbx.isRunning()`

Check whether the sandbox is currently running.

const running = await sbx.isRunning();

number

Per-request HTTP timeout in milliseconds.

Returns Promise<boolean>

`sbx.setTimeout()`

Update the sandbox timeout.

await sbx.setTimeout(600); // extend to 10 minutes from now

number

required

New timeout in seconds.

number

Per-request HTTP timeout in milliseconds.

Returns Promise<void>

`sbx.getInfo()`

Fetch current metadata and state of the sandbox.

const info = await sbx.getInfo();
console.log(info.state);     // SandboxState.Running
console.log(info.startedAt); // Date

number

Per-request HTTP timeout in milliseconds.

Returns Promise<SandboxInfo>

`sbx.getMetrics()`

Retrieve CPU, memory, and disk usage metrics.

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);
}

Date

Start of time range.

Date

End of time range.

number

Per-request HTTP timeout in milliseconds.

Returns Promise<SandboxMetrics[]>

`sbx.pause()`

Pause the sandbox.

await sbx.pause();

number

Per-request HTTP timeout in milliseconds.

Returns Promise<void>

`sbx.createSnapshot()`

Create a snapshot of the sandbox.

const snap = await sbx.createSnapshot();
console.log(snap.snapshotId);

number

Per-request HTTP timeout in milliseconds.

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

const url = sbx.getHost(8080);
// https://api.declaw.ai/sandboxes/sbx-.../ports/8080

number

required

The port number to proxy to inside the sandbox.

Returns string

`sbx.getMcpUrl()`

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

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.

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:

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`

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

`SandboxState`

enum SandboxState {
  Running  = 'running',
  Paused   = 'paused',
  Creating = 'creating',
  Killed   = 'killed',
}

`SandboxMetrics`

interface SandboxMetrics {
  timestamp: Date;
  cpuUsagePercent: number;
  memoryUsageMb: number;
  diskUsageMb: number;
}

`SandboxLifecycle`

interface SandboxLifecycle {
  onTimeout: string;    // "kill" or "pause"
  autoResume: boolean;
}

`SnapshotInfo`

interface SnapshotInfo {
  snapshotId: string;
  sandboxId: string;
  createdAt?: Date;
}

`SandboxQuery`

interface SandboxQuery {
  metadata?: Record<string, string>;
  state?: SandboxState[];
}

Python SDK

TypeScript SDK

Go SDK

Static methods

`Sandbox.create()`

`Sandbox.connect()`

`Sandbox.list()`

Instance methods

`sbx.kill()`

`sbx.isRunning()`

`sbx.setTimeout()`

`sbx.getInfo()`

`sbx.getMetrics()`

`sbx.pause()`

`sbx.createSnapshot()`

`sbx.getHost()`

`sbx.getMcpUrl()`

`sbx.close()`

Properties

Automatic disposal

Data models

`SandboxInfo`

`SandboxState`

`SandboxMetrics`

`SandboxLifecycle`

`SnapshotInfo`

`SandboxQuery`

​Static methods

​Sandbox.create()

​Sandbox.connect()

​Sandbox.list()

​Instance methods

​sbx.kill()

​sbx.isRunning()

​sbx.setTimeout()

​sbx.getInfo()

​sbx.getMetrics()

​sbx.pause()

​sbx.createSnapshot()

​sbx.getHost()

​sbx.getMcpUrl()

​sbx.close()

​Properties

​Automatic disposal

​Data models

​SandboxInfo

​SandboxState

​SandboxMetrics

​SandboxLifecycle

​SnapshotInfo

​SandboxQuery

Static methods

`Sandbox.create()`

`Sandbox.connect()`

`Sandbox.list()`

Instance methods

`sbx.kill()`

`sbx.isRunning()`

`sbx.setTimeout()`

`sbx.getInfo()`

`sbx.getMetrics()`

`sbx.pause()`

`sbx.createSnapshot()`

`sbx.getHost()`

`sbx.getMcpUrl()`

`sbx.close()`

Properties

Automatic disposal

Data models

`SandboxInfo`

`SandboxState`

`SandboxMetrics`

`SandboxLifecycle`

`SnapshotInfo`

`SandboxQuery`