Sandboxes

client.sandboxes manages sandbox lifecycle. create and get return a SandboxHandle — the sandbox object plus bound helpers — while list and kill return plain Sandbox objects.

create

Create a sandbox from a template. The call resolves once the sandbox record exists; check status and expiresAt on the returned handle.

create(input?: CreateSandboxInput): Promise<SandboxHandle>

const sandbox = await client.sandboxes.create({
  template: "python",
  ttlMs: 10 * 60 * 1000,
  metadata: { run: "nightly-eval" },
});

console.log(sandbox.id, sandbox.status, sandbox.expiresAt);

Error codes: invalid_request, forbidden, not_found, quota_exceeded, sandbox_ttl_exceeded (requested ttlMs exceeds your plan limit).

get

Fetch a sandbox by ID and get a handle bound to it.

get(sandboxId: `sbx_${string}`): Promise<SandboxHandle>

const sandbox = await client.sandboxes.get("sbx_abc123");
console.log(sandbox.status);

Error codes: not_found, forbidden.

list

List sandboxes visible to your API key. Live sandboxes are returned; destroyed and failed records are excluded by default.

list(): Promise<readonly Sandbox[]>

const sandboxes = await client.sandboxes.list();
for (const sandbox of sandboxes) {
  console.log(sandbox.id, sandbox.status);
}

kill

Destroy a sandbox. The operation is idempotent by state: killing an already destroyed sandbox returns the destroyed record. The returned sandbox has status destroyed and destroyedReason user_killed.

kill(sandboxId: `sbx_${string}`): Promise<Sandbox>

const destroyed = await client.sandboxes.kill(sandbox.id);
console.log(destroyed.status, destroyed.destroyedReason);

You can also call sandbox.kill() on a handle, which returns an updated SandboxHandle.

[!IMPORTANT] Killing a sandbox discards the workspace filesystem. Export anything you need to keep with artifacts first.

Error codes: not_found, forbidden.

Sandbox object

The Sandbox type includes id (sbx_ prefix), orgId, projectId, status (creating, starting, ready, running, idle, expiring, destroyed, failed), templateId, templateSlug, templateVersion, templateVersionId, ttlMs, expiresAt (ISO 8601), metadata, and — once destroyed — destroyedAt and destroyedReason.

Next steps

• Commands — run processes inside the sandbox.
• Files — manage the workspace filesystem.
• Sandboxes concept — lifecycle, TTL, and templates in depth.