Sandbox - Superserve

The Sandbox class is the main entry point for the SDK. Python ships both a sync Sandbox and an AsyncSandbox with identical method names.

Import

import { Sandbox } from "@superserve/sdk"

Authentication

The SDK reads SUPERSERVE_API_KEY from the environment by default. Pass apiKey / api_key explicitly to override, and baseUrl / base_url to target a different control-plane URL.

export SUPERSERVE_API_KEY=ss_live_...
export SUPERSERVE_BASE_URL=https://api.superserve.ai  # optional

Factory methods

`Sandbox.create`

Create and boot a new sandbox. Synchronous - when the promise resolves, the VM is active.

const sandbox = await Sandbox.create({
  name: "data-analyzer",
  timeoutSeconds: 3600,
  metadata: { env: "prod" },
  envVars: { OPENAI_API_KEY: "sk-..." },
  network: { allowOut: ["api.openai.com"], denyOut: ["0.0.0.0/0"] },
})

Options:

Option	Type	Description
`name`	`string`	Required. Human-readable sandbox name.
`fromTemplate` / `from_template`	`string \| Template`	Template name, UUID, or `Template` instance to boot from. Defaults to `superserve/base`.
`fromSnapshot` / `from_snapshot`	`string`	Snapshot UUID to boot from.
`timeoutSeconds` / `timeout_seconds`	`number`	Max active lifetime before auto-pause. API-side upper bound (subject to change).
`metadata`	`Record<string, string>`	String tags.
`envVars` / `env_vars`	`Record<string, string>`	Env vars injected into every process.
`network`	`NetworkConfig`	Egress allow/deny rules.
`apiKey` / `api_key`	`string`	Overrides `SUPERSERVE_API_KEY`.
`baseUrl` / `base_url`	`string`	Overrides `SUPERSERVE_BASE_URL`.
`signal`	`AbortSignal`	TypeScript only - abort the creation request.

`Sandbox.connect`

Reconnect to an existing sandbox by ID. Fetches info and a fresh access token.

const sandbox = await Sandbox.connect("7a3f2b8c-1234-...")

`Sandbox.list`

List sandboxes on the authenticated team. metadata filters combine with AND.

const all = await Sandbox.list()
const prod = await Sandbox.list({ metadata: { env: "prod" } })

Returns an array of SandboxInfo.

`Sandbox.killById` / `Sandbox.kill_by_id`

Delete a sandbox by ID without instantiating it. Idempotent.

await Sandbox.killById("7a3f2b8c-1234-...")

Methods on `sandbox`

`getInfo` / `get_info`

Fetch the current server-side state. Returns a fresh SandboxInfo - the returned sandbox’s own status / metadata properties are snapshots and are not mutated.

const info = await sandbox.getInfo()
console.log(info.status)  // "active" | "paused" | "resuming" | "failed"

`pause`

Checkpoint the VM state to disk. The sandbox transitions to paused. Returns nothing.

await sandbox.pause()

`resume`

Restore a paused sandbox. The backend rotates the per-sandbox access token; the SDK re-injects it into sandbox.files transparently.

await sandbox.resume()

`kill`

Delete the sandbox. Idempotent - swallows 404.

await sandbox.kill()

`update`

Patch metadata and/or network on a live sandbox.

await sandbox.update({
  metadata: { env: "staging" },
  network: { allowOut: ["api.openai.com"] },
})

Properties on `sandbox`

id, name, status, and metadata are read-only snapshots taken at construction. Call getInfo() / get_info() for fresh data.

Property	Type	Description
`id`	`string`	Unique sandbox UUID.
`name`	`string`	Human-readable name.
`status`	`SandboxStatus`	Status at construction time.
`metadata`	`Record<string, string>`	Tags at construction time.
`commands`	`Commands`	See Commands.
`files`	`Files`	See Files. Rebuilt after `resume()`.

Types

`SandboxStatus`

type SandboxStatus = "active" | "paused" | "resuming" | "failed"

active - running and ready to accept commands
paused - stopped with state saved to disk
resuming - transient, briefly visible while a paused sandbox is being restored to active (retry shortly)
failed - the sandbox couldn’t boot or resume; the entry remains until you delete it

Deletion removes the sandbox entirely - subsequent API calls return 404.

`SandboxInfo`

interface SandboxInfo {
  id: string
  name: string
  status: SandboxStatus
  vcpuCount: number
  memoryMib: number
  createdAt: Date
  timeoutSeconds?: number
  network?: NetworkConfig
  metadata: Record<string, string>
}

`NetworkConfig`

interface NetworkConfig {
  allowOut?: string[]  // CIDRs or domain patterns
  denyOut?: string[]   // CIDRs only - use "0.0.0.0/0" to deny all
}

Retries

GET and DELETE requests auto-retry on 429, 502, 503, 504, and network errors with exponential backoff + jitter (3 attempts max). POST and PATCH are not retried - the SDK surfaces the error so you can decide. See Errors.

Errors

Sandbox methods commonly raise:

AuthenticationError - missing or invalid API key
ValidationError - bad request body
NotFoundError - sandbox doesn’t exist (except kill / killById, which swallow 404)
ConflictError - wrong state (e.g., pausing an already-paused sandbox, or patching network while paused)
ServerError - platform error

See Errors for the full hierarchy.

Reference

Documentation Index

​Import

​Authentication

​Factory methods

​Sandbox.create

​Sandbox.connect

​Sandbox.list

​Sandbox.killById / Sandbox.kill_by_id

​Methods on sandbox

​getInfo / get_info

​pause

​resume

​kill

​update

​Properties on sandbox

​Types

​SandboxStatus

​SandboxInfo

​NetworkConfig

​Retries

​Errors