Connect to an existing sandbox - Superserve

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, it’s auto-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.