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.
`secrets`	`Record<string, string>`	Bind secrets to env vars (`ENV_VAR → secret name`). The agent sees a stand-in token; the real credential is attached to outbound requests. See Secrets.
`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. Returns a live sandbox with a fresh access token. If the sandbox is currently paused, it is auto-resumed before returning so it’s immediately usable.

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"] },
})

`attachSecret` / `attach_secret`

Bind a team secret to a live or paused sandbox under an environment variable. The sandbox sees a stand-in token; the real credential is swapped in for outbound requests to the secret’s allowed hosts. Takes effect for processes started after the call; a paused sandbox applies it on resume.

await sandbox.attachSecret("ANTHROPIC_API_KEY", "anthropic-prod")

`detachSecret` / `detach_secret`

Remove a secret binding by its environment-variable key. The stand-in token is revoked, so requests using it are refused — within about a minute for a process already running. A paused sandbox applies the change on resume.

await sandbox.detachSecret("ANTHROPIC_API_KEY")

`getNetworkLog` / `get_network_log`

The sandbox’s network log — every outbound connection and secret-bearing request, newest first. Returns a NetworkLogPage. See the Network log guide for the full model.

const page = await sandbox.getNetworkLog({ verdict: "blocked", limit: 100 })
for (const e of page.events) console.log(e.kind, e.host, e.verdict ?? e.status)

Option	Type	Description
`limit`	`number`	Max events per page.
`before`	`string`	Opaque pagination cursor — pass the previous page’s `nextCursor` to page through results. Also accepts an RFC3339 timestamp as a time filter (rows strictly older than it).
`since`	`string`	RFC3339 — rows at or newer than this.
`verdict`	`"allowed" \| "blocked" \| "failed"`	Filter to connections with this verdict (excludes request rows).

NetworkLogPage has events (NetworkEvent[]), nextCursor / next_cursor, and hasMore / has_more.

Properties on `sandbox`

id, name, status, metadata, and secrets 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.
`secrets`	`SandboxSecretBinding[] \| undefined`	Bound secrets (`envKey` → `secretName`, with a `revoked` flag) 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.

​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

​attachSecret / attach_secret

​detachSecret / detach_secret

​getNetworkLog / get_network_log

​Properties on sandbox

​Types

​SandboxStatus

​SandboxInfo

​NetworkConfig

​Retries

​Errors