Connect to an existing sandbox

A sandbox outlives the process that created it. Store sandbox.id somewhere durable (a database, a queue message), and reconnect later with Sandbox.connect().

Sandbox.connect(id) - returns a live sandbox with commands and files ready to use. If the sandbox is paused, or still pausing, it’s resumed before returning.
sandbox.getInfo() - fetch the current status and metadata for a sandbox you already have (read-only, no state change)

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.connect("7a3f2b8c-1234-...")
await sandbox.commands.run("ls /app")

from superserve import Sandbox

sandbox = Sandbox.connect("7a3f2b8c-1234-...")
sandbox.commands.run("ls /app")

Find sandboxes with `list`

List all sandboxes on the team, or narrow the result with filters. metadata returns only sandboxes matching every key-value pair you pass; status selects one lifecycle state; limit and offset page through large lists.

const all = await Sandbox.list()

const prod = await Sandbox.list({
  metadata: { env: "prod", owner: "agent-7" },
})

const running = await Sandbox.list({ status: "active" })

const page = await Sandbox.list({ limit: 100, offset: 100 })

for (const info of prod) {
  console.log(info.id, info.name, info.status)
}

all_boxes = Sandbox.list()

prod = Sandbox.list(metadata={"env": "prod", "owner": "agent-7"})

running = Sandbox.list(status="active")

page = Sandbox.list(limit=100, offset=100)

for info in prod:
    print(info.id, info.name, info.status.value)

list() returns an array of SandboxInfo - no live sandbox is constructed. Call Sandbox.connect(id) when you need one.

Automatic routing hints

Current TypeScript and Python SDKs carry the optional routing_hint returned by create, connect/activate, and resume on command, file, and session requests. The proxy uses this signed hint to select the sandbox’s logical host without looking up ownership on every new sandbox request. Authorization is unchanged. Raw HTTP callers can opt in by passing the response’s routing_hint as X-Superserve-Routing-Hint alongside X-Access-Token. Replace both values after resume or activate. For a WebSocket session, add route.<routing_hint> to the subprotocol list alongside superserve.exec.v1 and token.<access_token>. Callers that omit the hint keep working through ownership lookup, including its existing latency and capacity limits. Hints expire after one hour. SDKs refresh expired hints before their next operation and refresh a rejected stale route once through activate. A routing hint grants no access by itself. Never replay a command after an ambiguous connection loss or timeout: it may already have executed.

Get Started

Sandbox

Secrets & env vars

Templates

Commands

Filesystem

Storage

Errors

Connect to an existing sandbox

Find sandboxes with `list`

Automatic routing hints

​Find sandboxes with list

​Automatic routing hints

Find sandboxes with `list`

Automatic routing hints