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"

from superserve import Sandbox
# Async variant with awaitable methods:
from superserve import AsyncSandbox

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

from superserve import Sandbox, NetworkConfig

sandbox = Sandbox.create(
    name="data-analyzer",
    timeout_seconds=3600,
    metadata={"env": "prod"},
    env_vars={"OPENAI_API_KEY": "sk-..."},
    network=NetworkConfig(
        allow_out=["api.openai.com"],
        deny_out=["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`	Auto-pause after this many seconds of active time (per session; re-armed on resume). See Lifecycle.
`autoDeleteSeconds` / `auto_delete_seconds`	`number`	Delete the sandbox once continuously paused for this many seconds (max 30 days, `0` = delete on pause). See Lifecycle.
`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 = 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" } })

all_boxes = Sandbox.list()
prod = 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-...")

Sandbox.kill_by_id("7a3f2b8c-1234-...")

`Sandbox.updateById` / `Sandbox.update_by_id`

Update a sandbox by ID without instantiating it. Unlike connect(id) followed by update(...), this does not resume a paused sandbox — so it’s the right way to arm auto-delete or change the auto-pause timeout on a box you want to leave paused. Same fields and clear-with-null/None semantics as update.

await Sandbox.updateById("7a3f2b8c-1234-...", { autoDeleteSeconds: 3600 })

Sandbox.update_by_id("7a3f2b8c-1234-...", auto_delete_seconds=3600)

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"

info = sandbox.get_info()
print(info.status.value)  # "active" | "paused" | "resuming" | "failed"

`pause`

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

await sandbox.pause()

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

sandbox.resume()

`kill`

Delete the sandbox. Idempotent - swallows 404.

await sandbox.kill()

sandbox.kill()

`update`

Patch metadata, network, autoDeleteSeconds, and/or timeoutSeconds on a sandbox.

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

// Auto-delete: a number arms the window, null disarms it.
await sandbox.update({ autoDeleteSeconds: 3600 })
await sandbox.update({ autoDeleteSeconds: null })

// Auto-pause timeout: same set/clear contract.
await sandbox.update({ timeoutSeconds: 900 })
await sandbox.update({ timeoutSeconds: null })

sandbox.update(
    metadata={"env": "staging"},
    network=NetworkConfig(allow_out=["api.openai.com"]),
)

# Auto-delete: a number arms the window, None disarms it.
sandbox.update(auto_delete_seconds=3600)
sandbox.update(auto_delete_seconds=None)

# Auto-pause timeout: same set/clear contract.
sandbox.update(timeout_seconds=900)
sandbox.update(timeout_seconds=None)

On an already-paused sandbox, arming autoDeleteSeconds starts the countdown from the moment of the call — never retroactively from when the sandbox paused. See Lifecycle.

`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")

sandbox.attach_secret("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")

sandbox.detach_secret("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)

page = sandbox.get_network_log(verdict="blocked", limit=100)
for e in page.events:
    print(e.kind, e.host, e.verdict or 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"

from enum import Enum

class SandboxStatus(str, Enum):
    ACTIVE = "active"
    PAUSED = "paused"
    RESUMING = "resuming"
    FAILED = "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
  autoDeleteSeconds?: number
  autoDeleteAt?: Date // present only while paused with autoDeleteSeconds set
  network?: NetworkConfig
  metadata: Record<string, string>
}

from datetime import datetime
from pydantic import BaseModel

class SandboxInfo(BaseModel):
    id: str
    name: str
    status: SandboxStatus
    vcpu_count: int
    memory_mib: int
    created_at: datetime
    timeout_seconds: int | None = None
    auto_delete_seconds: int | None = None
    # Set only while paused with auto_delete_seconds configured.
    auto_delete_at: datetime | None = None
    network: NetworkConfig | None = None
    metadata: dict[str, str]

`NetworkConfig`

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

from pydantic import BaseModel

class NetworkConfig(BaseModel):
    allow_out: list[str] | None = None  # CIDRs or domain patterns
    deny_out: list[str] | None = None   # CIDRs only

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

​Sandbox.updateById / Sandbox.update_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