Skip to main content
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',
});
​
opts
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',
});
​
sandboxId
string
required
The sandbox ID to connect to. Must be alphanumeric with hyphens/underscores.
​
opts
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',
});
​
opts.query
Record<string, string>
Filter query parameters passed directly to the API.
​
opts.limit
number
Maximum number of sandboxes to return.
​
opts.nextToken
string
Pagination cursor from a previous list() call.
​
opts.apiKey
string
API key override.
​
opts.domain
string
Domain override.
​
opts.requestTimeout
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
​
requestTimeout
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();
​
requestTimeout
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
​
timeout
number
required
New timeout in seconds.
​
requestTimeout
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
​
requestTimeout
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);
}
​
opts.start
Date
Start of time range.
​
opts.end
Date
End of time range.
​
opts.requestTimeout
number
Per-request HTTP timeout in milliseconds.
Returns Promise<SandboxMetrics[]>

​
sbx.pause()

Pause the sandbox. 
await sbx.pause();
​
requestTimeout
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);
​
requestTimeout
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
​
port
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

PropertyTypeDescription
sbx.sandboxIdstringUnique sandbox identifier.
sbx.configConnectionConfigConnection config used by this instance.
sbx.envdAccessTokenstring | undefinedAccess token for the in-VM envd service.
sbx.sandboxDomainstring | undefinedDomain where the sandbox is accessible.
sbx.trafficAccessTokenstring | undefinedToken for traffic routing.
sbx.commandsCommandsCommands sub-module.
sbx.filesFilesystemFilesystem sub-module.
sbx.ptyPtyPTY 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[];
}