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

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"],
    ),
    preview_access="private",
)

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.
`previewAccess` / `preview_access`	`"public" \| "private"`	Enable explicit publication and set the default access for newly published ports. Each port can override it. Omit to use strict `public`; `legacy_public` is only returned for pre-migration sandboxes. See Preview URLs.
`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, lifecycle windows, and/or the default access for newly published preview ports 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 })

await sandbox.update({ previewAccess: "private" })

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)

sandbox.update(preview_access="private")

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. Moving a compatibility sandbox onto public or private closes every unpublished port. See Preview URLs for the safe publication and migration flow. Changing between public and private later does not rewrite the access mode of ports that are already published.

Preview URL methods

Preview URLs use an explicit published-port allowlist. The URL builder alone does not publish or authenticate a port.

TypeScript	Python	Description
`getPreviewUrl(port)`	`get_preview_url(port)`	Construct `https://{port}-{id}.{host}` without a network call.
`listPreviewPorts()`	`list_preview_ports()`	Return the sandbox default plus every port’s access; tokens are never listed.
`publishPreviewPort(port, { access? })`	`publish_preview_port(port, access=...)`	Publish a port; omit access to preserve an existing mode or use the new-port default.
`unpublishPreviewPort(port)`	`unpublish_preview_port(port)`	Close a port and revoke its credentials.
`getPreviewToken(port, options?)`	`get_preview_token(port, expires_in_seconds=...)`	Mint a per-port header/query credential.
`getSignedPreviewUrl(port, options?)`	`get_signed_preview_url(port, expires_in_seconds=60)`	Mint a browser bootstrap URL; defaults to 60 seconds.
`rotatePreviewToken(port)`	`rotate_preview_token(port)`	Revoke one port’s old credentials and return a fresh token.

See the Preview URLs guide for policy selection, machine headers, browser cookies, and revocation examples.

`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, previewAccess / preview_access, 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.
`previewAccess` / `preview_access`	`"legacy_public" \| "public" \| "private"`	Preview compatibility mode or default access for newly published ports 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>
  previewAccess: "legacy_public" | "public" | "private"
}

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]
    preview_access: PreviewAccess

`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

​Preview URL methods

​attachSecret / attach_secret

​detachSecret / detach_secret

​getNetworkLog / get_network_log

​Properties on sandbox

​Types

​SandboxStatus

​SandboxInfo

​NetworkConfig

​Retries

​Errors