### Superserve CLI Quick Start

Source: https://github.com/superserve-ai/superserve/blob/main/packages/cli/README.md

A quick guide to get started with the Superserve CLI, including login, project initialization, deployment, and running an agent.

```bash
superserve login                    # Authenticate (opens browser)
superserve init                     # Create superserve.yaml in your project
superserve deploy                   # Deploy your agent
superserve run my-agent             # Interactive chat with your agent
```

--------------------------------

### Quickstart Guide MDX Page

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-plan.md

This MDX file provides a quickstart guide for getting started with Superserve, including prerequisites and SDK usage examples.

```mdx
---
title: Quickstart
description: Get up and running with Superserve in under 5 minutes.
---

## Prerequisites

Get your API key from the [Superserve Console](https://console.superserve.ai).

Set it as an environment variable:

```bash
export SUPERSERVE_API_KEY=ss_live_...
```

## TypeScript

Install the SDK:

```bash
npm install @superserve/sdk
```

Create and use a sandbox:

```typescript
import { Sandbox } from "@superserve/sdk"

// Create a sandbox
const sandbox = await Sandbox.create({ name: "quickstart" })
await sandbox.waitForReady()

// Run a command
const result = await sandbox.commands.run("echo 'Hello from Superserve!'")
console.log(result.stdout)

// Write and read a file
await sandbox.files.write("/tmp/hello.txt", "Hello, world!")
const content = await sandbox.files.readText("/tmp/hello.txt")
console.log(content)

// Clean up
await sandbox.kill()
```

## Python

Install the SDK:

```bash
pip install superserve
```

Create and use a sandbox:

```python
from superserve import Sandbox

# Create a sandbox
sandbox = Sandbox.create(name="quickstart")
sandbox.wait_for_ready()

# Run a command
result = sandbox.commands.run("echo 'Hello from Superserve!'")
print(result.stdout)

# Write and read a file
sandbox.files.write("/tmp/hello.txt", b"Hello, world!")
content = sandbox.files.read_text("/tmp/hello.txt")
print(content)

```

--------------------------------

### TypeScript Quick Start Setup

Source: https://github.com/superserve-ai/superserve/blob/main/recipes/claude/research-agent/README.md

Commands to set up the TypeScript environment for the research agent. Includes installing dependencies, copying the environment file, and filling in API keys.

```bash
cd typescript
npm install
cp .env.example .env  # fill in your API keys
```

--------------------------------

### Python Quick Start Setup

Source: https://github.com/superserve-ai/superserve/blob/main/recipes/claude/research-agent/README.md

Commands to set up the Python environment for the research agent. Includes installing dependencies, copying the environment file, and filling in API keys.

```bash
cd python
uv sync
cp .env.example .env  # fill in your API keys
```

--------------------------------

### Python Quick Start: Build Template

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to build the Superserve sandbox template using Python. This is a one-time setup step.

```bash
uv run build_template.py
```

--------------------------------

### Python Quick Start: Create Environment

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to create a self-hosted environment on the Claude Platform using Python. This is a one-time setup step.

```bash
uv run create_environment.py
```

--------------------------------

### Python Quick Start: Build and Run Agent

Source: https://github.com/superserve-ai/superserve/blob/main/recipes/claude/parallel-benchmark-agent/README.md

Commands to set up the Python environment for the benchmark agent. Includes installing dependencies, configuring API keys, and running the build, create, and orchestrator scripts.

```bash
cd python
uv sync
cp .env.example .env  # fill in your API keys
```

```bash
uv run build_template.py         # one-time
uv run create_agent.py my-agent  # one-time
uv run orchestrator.py           # long-running
```

--------------------------------

### TypeScript Quick Start: Create Environment

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to create a self-hosted environment on the Claude Platform using TypeScript. This is a one-time setup step.

```bash
node create-environment.mjs
```

--------------------------------

### Python Quick Start: Create Agent

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to create an agent with specified tools (bash, file, web) enabled using Python. This is a one-time setup step.

```bash
uv run create_agent.py my-agent
```

--------------------------------

### TypeScript Quick Start: Build and Run Agent

Source: https://github.com/superserve-ai/superserve/blob/main/recipes/claude/parallel-benchmark-agent/README.md

Commands to set up the TypeScript environment for the benchmark agent. Includes installing dependencies, configuring API keys, and running the build, create, and orchestrator scripts.

```bash
cd typescript
npm install
cp .env.example .env  # fill in your API keys
```

```bash
node build-template.mjs         # one-time
node create-agent.mjs my-agent  # one-time
node orchestrator.mjs           # long-running
```

--------------------------------

### TypeScript Quick Start: Build Template

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to build the Superserve sandbox template using TypeScript. This is a one-time setup step.

```bash
node build-template.mjs
```

--------------------------------

### Start Local Docs Development Server

Source: https://github.com/superserve-ai/superserve/blob/main/CLAUDE.md

Starts a local development server for the documentation using Mintlify.

```bash
bun run docs:dev
```

--------------------------------

### TypeScript Quick Start: Create Agent

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to create an agent with specified tools (bash, file, web) enabled using TypeScript. This is a one-time setup step.

```bash
node create-agent.mjs my-agent
```

--------------------------------

### Superserve YAML Configuration Example

Source: https://github.com/superserve-ai/superserve/blob/main/packages/cli/README.md

Example configuration file (`superserve.yaml`) for defining an agent. Specifies agent name, start command, environment secrets, and files to ignore.

```yaml
name: my-agent # Agent name (required)
command: python main.py # Start command (required)
secrets: # Environment variables (optional)
  - ANTHROPIC_API_KEY
ignore: # Exclude from upload (optional)
  - .venv
```

--------------------------------

### Start Local Development Server

Source: https://github.com/superserve-ai/superserve/blob/main/docs/README.md

Use this command to start the local development server for Superserve. Preview the application at http://localhost:3000.

```bash
npx mint dev # or bunx mint dev
```

--------------------------------

### Start UI Docs Dev Server

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-05-radix-to-baseui-migration-plan.md

Starts the development server for the UI documentation project using Turbo. This command is used to visually verify each component after the migration.

```bash
cd /Users/nirnejak/Code/superserve/superserve
bunx turbo run dev --filter=@superserve/ui-docs
```

--------------------------------

### Install Superserve SDK

Source: https://github.com/superserve-ai/superserve/blob/main/packages/sdk/README.md

Install the SDK using npm, bun, or pnpm. It has zero runtime dependencies and requires Node.js 18+ or a modern browser/runtime with fetch.

```bash
npm install @superserve/sdk
# or
bun add @superserve/sdk
# or
pnpm add @superserve/sdk
```

--------------------------------

### Install Superserve SDK

Source: https://github.com/superserve-ai/superserve/blob/main/docs/quickstart.mdx

Install the Superserve SDK using npm for Node.js or pip for Python.

```bash
npm install @superserve/sdk
```

```bash
pip install superserve
```

--------------------------------

### Start All Development Servers

Source: https://github.com/superserve-ai/superserve/blob/main/README.md

Starts all development servers for the monorepo packages.

```bash
bun run dev
```

--------------------------------

### Python SDK README

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-plan.md

Provide a README for the superserve package, including installation, quick start, async usage, and authentication for the Python SDK.

```markdown
# superserve

Python SDK for the Superserve sandbox API.

## Installation

```bash
pip install superserve
```

## Quick Start

```python
from superserve import Sandbox

sandbox = Sandbox.create(name="my-sandbox")
sandbox.wait_for_ready()

result = sandbox.commands.run("echo hello")
print(result.stdout)

sandbox.files.write("/app/data.txt", b"content")
text = sandbox.files.read_text("/app/data.txt")

sandbox.kill_instance()
```

## Async

```python
from superserve import AsyncSandbox

sandbox = await AsyncSandbox.create(name="my-sandbox")
await sandbox.wait_for_ready()

result = await sandbox.commands.run("echo hello")
await sandbox.kill_instance()
```

## Authentication

Set the `SUPERSERVE_API_KEY` environment variable, or pass `api_key` explicitly:

```python
sandbox = Sandbox.create(name="my-sandbox", api_key="ss_live_...")
```
```

--------------------------------

### Install Superserve SDK and Set API Key

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/coding-agents/claude.mdx

Install the necessary SDK package and set your Superserve API key as an environment variable before using the SDK.

```bash
npm install @superserve/sdk
export SUPERSERVE_API_KEY=ss_live_...
```

--------------------------------

### Install and Run Opencode via Console

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/coding-agents/opencode.mdx

Use this command in the Superserve sandbox terminal to install Opencode and add its bin directory to the PATH.

```bash
curl -fsSL https://opencode.ai/install | bash && opencode
export PATH=/home/user/.opencode/bin:$PATH
```

--------------------------------

### Install Superserve CLI

Source: https://github.com/superserve-ai/superserve/blob/main/packages/cli/README.md

Install the Superserve CLI globally using Bun. This command makes the `superserve` executable available in your terminal.

```bash
bun install -g superserve
```

--------------------------------

### Create Sandbox and Install Codex (Python)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/coding-agents/codex.mdx

Use the Superserve SDK in Python to create a new sandbox from a template, set environment variables, and install the OpenAI Codex CLI.

```python
from superserve import Sandbox

sandbox = Sandbox.create(
    name="codex",
    from_template="superserve/node-22",
    env_vars={"OPENAI_API_KEY": "sk-..."},
)

sandbox.commands.run("npm install -g @openai/codex")
```

--------------------------------

### Install TanStack Query

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-plan.md

Installs the @tanstack/react-query package for the console application using Bun.

```bash
cd /Users/nirnejak/Code/superserve/superserve && bun add @tanstack/react-query --filter @superserve/console
```

--------------------------------

### Define Start Command

Source: https://github.com/superserve-ai/superserve/blob/main/docs/templates/build-spec.mdx

Specify the command to start your application after the build is complete. The snapshot captures the running process, so sandboxes restored from this template will have the application already live.

```typescript
startCmd: "python server.py"
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/superserve-ai/superserve/blob/main/README.md

Installs all Python dependencies using uv sync.

```bash
uv sync
```

--------------------------------

### Start Development Server for Console

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-plan.md

Launches the development server for the '@superserve/console' package using the Turbo build tool.

```bash
cd /Users/nirnejak/Code/superserve/superserve && bunx turbo run dev --filter=@superserve/console
```

--------------------------------

### Install Dependencies (Python)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/agent-harnesses/openai-agents-sdk.mdx

Install the necessary packages for using Superserve SDK and OpenAI Agents SDK with Python. Set your Superserve API key.

```bash
pip install superserve openai-agents
export SUPERSERVE_API_KEY=ss_live_...
```

--------------------------------

### Install Superserve Python SDK

Source: https://github.com/superserve-ai/superserve/blob/main/packages/python-sdk/README.md

Install the Superserve Python SDK using pip, uv, or poetry. Requires Python version 3.9 or higher.

```bash
pip install superserve
```

```bash
# or
uv add superserve
```

```bash
# or
poetry add superserve
```

--------------------------------

### Run Dev Server

Source: https://github.com/superserve-ai/superserve/blob/main/apps/console/README.md

Starts the development server for the console application.

```bash
bun --filter @superserve/console run dev
```

--------------------------------

### Run Email Template Preview

Source: https://github.com/superserve-ai/superserve/blob/main/apps/console/README.md

Starts the email template preview server with hot reload.

```bash
bun --filter @superserve/console run email:dev
```

--------------------------------

### Create Sandbox and Install Codex (TypeScript)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/coding-agents/codex.mdx

Use the Superserve SDK in TypeScript to create a new sandbox from a template, set environment variables, and install the OpenAI Codex CLI.

```typescript
import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "codex",
  fromTemplate: "superserve/node-22",
  envVars: { OPENAI_API_KEY: "sk-..." },
})

await sandbox.commands.run("npm install -g @openai/codex")
```

--------------------------------

### Quick Start with Superserve Sandbox

Source: https://github.com/superserve-ai/superserve/blob/main/packages/python-sdk/README.md

Create a sandbox, run a command, write and read a file, and then kill the sandbox. This demonstrates basic SDK functionality.

```python
from superserve import Sandbox

sandbox = Sandbox.create(name="my-sandbox")

result = sandbox.commands.run("echo hello")
print(result.stdout)

sandbox.files.write("/app/data.txt", b"content")
text = sandbox.files.read_text("/app/data.txt")

sandbox.kill()
```

--------------------------------

### Commit Changes to Get Started Page

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-plan.md

Stages and commits the modified 'page.tsx' file for the get started page with a descriptive commit message.

```bash
cd /Users/nirnejak/Code/superserve/superserve && git add apps/console/src/app/\(dashboard\)/get-started/page.tsx && git commit -m "console: wire get started page to use API key mutation"
```

--------------------------------

### Create a Basic Sandbox

Source: https://github.com/superserve-ai/superserve/blob/main/docs/sandbox/create.mdx

Boots a fresh VM and returns when it's ready to use. The returned instance is already active.

```typescript
import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "data-analyzer" })
```

```python
from superserve import Sandbox

sandbox = Sandbox.create(name="data-analyzer")
```

--------------------------------

### Remove Mock Key Generation Function

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-plan.md

Removes the local mock key generation function from the get started page component.

```typescript
function generateMockKey(): { full: string; prefix: string } {
  const chars = "abcdefghijklmnopqrstuvwxyz0123456789"
  let key = ""
  for (let i = 0; i < 32; i++) {
    key += chars[Math.floor(Math.random() * chars.length)]
  }
  const full = `ss_live_${key}`
  const prefix = `ss_live_${key.slice(0, 8)}...`
  return { full, prefix }
}
```

--------------------------------

### Create and Use a Sync Sandbox Instance

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-plan.md

Demonstrates the basic usage of the Sandbox class, including creation, waiting for readiness, running commands, and file operations. Ensure the SDK is installed and configured.

```python
"""Sync Sandbox class — primary entry point for the Superserve Python SDK.

Usage::

    from superserve import Sandbox

    sandbox = Sandbox.create(name="my-sandbox")
    sandbox.wait_for_ready()

    result = sandbox.commands.run("echo hello")
    print(result.stdout)

    sandbox.files.write("/app/data.txt", b"content")
    text = sandbox.files.read_text("/app/data.txt")

    sandbox.kill()
"""

from __future__ import annotations

from typing import Any, Dict, List, Optional

from ._config import ResolvedConfig, resolve_config
from ._http import api_request
from ._polling import wait_for_status
from .commands import Commands
from .files import Files
from .types import (
    NetworkConfig,
    SandboxInfo,
    SandboxStatus,
    to_sandbox_info,
)


class Sandbox:
    """A connected sandbox instance with lifecycle methods and sub-modules."""

    def __init__(self, info: SandboxInfo, config: ResolvedConfig) -> None:
        self.id: str = info.id
        self.name: str = info.name
        self.status: SandboxStatus = info.status
        self.metadata: Dict[str, str] = info.metadata
        self.access_token: str = info.access_token
        self._config = config

        self.commands = Commands(config.base_url, self.id, config.api_key)
        self.files = Files(self.id, config.sandbox_host, self.access_token)

    # ----- Static factory methods -----

    @classmethod
    def create(
        cls,
        *,
        name: str,
        from_snapshot: Optional[str] = None,
        timeout_seconds: Optional[int] = None,
        metadata: Optional[Dict[str, str]] = None,
        env_vars: Optional[Dict[str, str]] = None,
        network: Optional[NetworkConfig] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
    ) -> Sandbox:
        """Create a new sandbox."""
        config = resolve_config(api_key=api_key, base_url=base_url)

        body: Dict[str, Any] = {"name": name}
        if from_snapshot:
            body["from_snapshot"] = from_snapshot
        if timeout_seconds:
            body["timeout_seconds"] = timeout_seconds
        if metadata:
            body["metadata"] = metadata
        if env_vars:
            body["env_vars"] = env_vars
        if network:
            body["network"] = {
                "allow_out": network.allow_out,
                "deny_out": network.deny_out,
            }

        raw = api_request(
            "POST",
            f"{config.base_url}/sandboxes",
            headers={"X-API-Key": config.api_key},
            json_body=body,
        )
        return cls(to_sandbox_info(raw), config)

    @classmethod
    def connect(
        cls,
        sandbox_id: str,
        *,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
    ) -> Sandbox:
        """Connect to an existing sandbox by ID."""
        config = resolve_config(api_key=api_key, base_url=base_url)
        raw = api_request(
            "GET",
            f"{config.base_url}/sandboxes/{sandbox_id}",
            headers={"X-API-Key": config.api_key},
        )
        return cls(to_sandbox_info(raw), config)

    @classmethod
    def list(
        cls,
        *,
        metadata: Optional[Dict[str, str]] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
    ) -> List[SandboxInfo]:
        """List all sandboxes belonging to the authenticated team."""
        config = resolve_config(api_key=api_key, base_url=base_url)
        url = f"{config.base_url}/sandboxes"
        if metadata:
            from urllib.parse import urlencode

            params = {f"metadata.{k}": v for k, v in metadata.items()}
            url += f"?{urlencode(params)}"

        raw = api_request("GET", url, headers={"X-API-Key": config.api_key})
        return [to_sandbox_info(item) for item in raw]

    @classmethod
    def get(
        cls,
        sandbox_id: str,
        *,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
    ) -> SandboxInfo:
        """Get sandbox info by ID."""
        config = resolve_config(api_key=api_key, base_url=base_url)
        raw = api_request(
            "GET",
            f"{config.base_url}/sandboxes/{sandbox_id}",
            headers={"X-API-Key": config.api_key},
        )
        return to_sandbox_info(raw)

    @classmethod
    def kill(
        cls,
        sandbox_id: str,
        *,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
    ) -> None:
        """Delete a sandbox by ID."""
        config = resolve_config(api_key=api_key, base_url=base_url)
        api_request(
            "DELETE",
            f"{config.base_url}/sandboxes/{sandbox_id}",

```

--------------------------------

### TypeScript SDK README

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-plan.md

Provide a README for the @superserve/sdk package, including installation, quick start, and authentication details for the TypeScript SDK.

```markdown
# @superserve/sdk

TypeScript SDK for the Superserve sandbox API.

## Installation

```bash
npm install @superserve/sdk
```

## Quick Start

```typescript
import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({ name: "my-sandbox" })
await sandbox.waitForReady()

const result = await sandbox.commands.run("echo hello")
console.log(result.stdout)

await sandbox.files.write("/app/data.txt", "content")
const text = await sandbox.files.readText("/app/data.txt")

await sandbox.kill()
```

## Authentication

Set the `SUPERSERVE_API_KEY` environment variable, or pass `apiKey` explicitly:

```typescript
const sandbox = await Sandbox.create({
  name: "my-sandbox",
  apiKey: "ss_live_...",
})
```
```

--------------------------------

### Quick Start: Initialize and Use Sandbox

Source: https://github.com/superserve-ai/superserve/blob/main/packages/sdk/README.md

Initialize a sandbox, run a command, write and read a file, and then terminate the sandbox. The Sandbox.create() method is asynchronous and ready to use upon resolution.

```typescript
import { Sandbox } from "@superserve/sdk"

// Sandbox is ready to use when create() returns.
const sandbox = await Sandbox.create({ name: "my-sandbox" })

const result = await sandbox.commands.run("echo hello")
console.log(result.stdout)

await sandbox.files.write("/app/data.txt", "content")
const text = await sandbox.files.readText("/app/data.txt")

await sandbox.kill()
```

--------------------------------

### Environment Configuration Examples

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-design.md

Demonstrates how to configure the Sandbox client, including setting a custom base URL for staging or local development environments.

```typescript
const sandbox = await Sandbox.create({ name: "my-sandbox" })

const sandbox = await Sandbox.create({
  name: "my-sandbox",
  apiKey: "ss_live_...",
  baseUrl: "https://api-staging.superserve.ai",
})
```

--------------------------------

### Create and Use a Template in Python (Sync)

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-24-templates-sdk-docs-design.md

Demonstrates creating a new template with specified configurations, including build steps, environment variables, and start commands. It then waits for the template to be ready and creates a sandbox from it.

```python
from superserve import Template, Sandbox
from superserve.types import RunStep, EnvStep, EnvStepValue, WorkdirStep, UserStep, UserStepValue

template = Template.create(
    alias="my-python-env",
    vcpu=2,
    memory_mib=2048,
    disk_mib=4096,
    from_="python:3.11",
    steps=[
        RunStep(run="pip install numpy pandas"),
        EnvStep(env=EnvStepValue(key="DEBUG", value="1")),
        WorkdirStep(workdir="/app"),
        UserStep(user=UserStepValue(name="appuser", sudo=True)),
    ],
    start_cmd="python server.py",
    ready_cmd="curl -f http://localhost:8080/health",
)

template.wait_until_ready(
    on_log=lambda ev: print(ev.text, end="") if ev.stream != "system" else None,
)

sandbox = Sandbox.create(name="run-1", from_template=template)

```

--------------------------------

### TanStack Query Status Polling for Sandbox Creation

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-design.md

Example of using TanStack Query to poll for sandbox status updates after creation. It refetches every 2 seconds while the status is 'starting'.

```typescript
useQuery({
  queryKey: sandboxKeys.detail(id),
  queryFn: () => getSandbox(id),
  refetchInterval: (query) =>
    query.state.data?.status === "starting" ? 2000 : false,
})
```

--------------------------------

### Handle Session Status Run Started Webhook

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/managed-agents/claude-managed-agents.mdx

Subscribe to session status webhooks to process work items. This example shows how to unwrap and filter webhook events, then drain the work queue.

```typescript
import Anthropic from "@anthropic-ai/sdk"

const client = new Anthropic({ authToken: environmentKey })

export async function handleWebhook(req: Request): Promise<Response> {
  const body = await req.text()
  const event = client.beta.webhooks.unwrap(body, {
    headers: Object.fromEntries(req.headers),
  })
  if (event.data.type !== "session.status_run_started") {
    return Response.json({ status: "ignored" })
  }

  for await (const work of client.beta.environments.work.poller({
    environmentId,
    environmentKey,
    blockMs: null,
    drain: true,
    autoStop: false,
  })) {
    await handleWork(work)
  }
  return Response.json({ status: "ok" })
}
```

--------------------------------

### Build and Publish with UV

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-09-fern-sdk-docs-design.md

Use `uv build` to build the package and `uv publish` to publish it. Publishing requires the `UV_PUBLISH_TOKEN` environment variable to be set.

```bash
uv build
uv publish             # requires UV_PUBLISH_TOKEN
```

--------------------------------

### Test GET request without body

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-24-templates-sdk-docs-plan.md

This test verifies that the `stream_sse` function correctly uses a GET request without sending a JSON body when the method is specified as GET.

```python
class TestStreamSSEGet:
    def test_uses_get_without_body(self) -> None:
        with respx.mock() as router:
            route = router.get("https://api.example.com/templates/t/builds/b/logs").mock(
                return_value=httpx.Response(
                    200,
                    text=(
                        'data: {"timestamp":"2026-01-01T00:00:00Z","stream":"stdout","text":"hi"}\n\n'
                        'data: {"timestamp":"2026-01-01T00:00:01Z","stream":"system","text":"done","finished":true,"status":"ready"}\n\n'
                    ),
                )
            )
            events: list[dict] = []
            stream_sse(
                "https://api.example.com/templates/t/builds/b/logs",
                headers={"X-API-Key": "k"},
                json_body=None,
                method="GET",
                on_event=lambda ev: events.append(ev),
            )
            assert len(events) == 2
            assert route.call_count == 1
            # GET request has no body
            assert route.calls.last.request.content == b""
```

--------------------------------

### Create Sandbox and Run Commands (Python)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/quickstart.mdx

Create a sandbox, run an echo command, write to a file, read the file content, and then terminate the sandbox using the Superserve SDK in Python.

```python
from superserve import Sandbox

sandbox = Sandbox.create(name="quickstart")

result = sandbox.commands.run("echo 'Hello from Superserve!'")
print(result.stdout)

sandbox.files.write("/tmp/hello.txt", "Hello, world!")
content = sandbox.files.read_text("/tmp/hello.txt")
print(content)

sandbox.kill()
```

--------------------------------

### Run Local Fern Docs Preview

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-09-fern-sdk-docs-plan.md

Navigates to the fern directory and starts a local development server for previewing the Fern Docs site.

```bash
cd fern && bunx fern docs dev
```

--------------------------------

### Verify xterm.js Installation

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-08-web-terminal-plan.md

Checks if the xterm.js packages have been successfully installed in the node_modules directory.

```bash
ls node_modules/@xterm/xterm/package.json && ls node_modules/@xterm/addon-fit/package.json
```

--------------------------------

### Verify Introduction File Content

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-09-fern-sdk-docs-plan.md

Displays the content of the newly ported introduction markdown file to ensure it matches the original.

```bash
cat docs/pages/introduction.mdx
```

--------------------------------

### Install JavaScript/TypeScript Dependencies

Source: https://github.com/superserve-ai/superserve/blob/main/README.md

Installs all JS/TS dependencies for the monorepo using Bun workspaces.

```bash
bun install
```

--------------------------------

### Create Docs Pages Directory and Port Introduction File

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-09-fern-sdk-docs-plan.md

Creates a new directory for Fern documentation pages and copies the existing introduction markdown file into it.

```bash
mkdir -p docs/pages
cp docs/introduction.mdx docs/pages/introduction.mdx
```

--------------------------------

### Get Template Info

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-24-templates-sdk-docs-plan.md

Retrieves detailed information about a specific template instance. This instance method makes a GET request to the /templates/{id} endpoint.

```APIDOC
## GET /templates/{id}

### Description
Retrieves detailed information about a specific template instance.

### Method
GET

### Endpoint
/templates/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The ID of the template to retrieve information for.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **template_info** (TemplateInfo) - An object containing detailed information about the template.

#### Response Example
```json
{
  "example": "{\n  \"id\": \"tpl_abc123\",\n  \"name\": \"My First Template\",\n  \"description\": \"A template for my project.\",\n  \"created_at\": \"2023-01-01T12:00:00Z\",\n  \"updated_at\": \"2023-01-01T12:00:00Z\"\n}"
}
```
```

--------------------------------

### Python SDK: Create Sandbox

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-design.md

Demonstrates creating a new sandbox with various configuration options. The API key and base URL can be provided directly or fall back to environment variables.

```python
from superserve import Sandbox

# Create
sandbox = Sandbox.create(
    name="my-sandbox",
    from_snapshot="snapshot-uuid",       # optional
    timeout_seconds=3600,               # optional
    metadata={"env": "prod"},           # optional
    env_vars={"API_KEY": "..."},        # optional
    api_key="ss_live_...",              # optional, falls back to env var
    base_url="https://api.superserve.ai",  # optional
)
```

--------------------------------

### Developer Loop: Regenerate and Build

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-09-fern-sdk-docs-design.md

Illustrates the command sequence for regenerating SDKs after a backend spec change and subsequently building the generated code.

```bash
# backend team merges a spec change in github.com/superserve-ai/sandbox
bun run generate              # Fern fetches latest openapi.yaml from URL and regenerates
bun run build                 # tsup TS, uv build Python
# apps/console picks up the new SDK on next build/dev

```

--------------------------------

### Install Dependencies (TypeScript)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/agent-harnesses/openai-agents-sdk.mdx

Install the necessary packages for using Superserve SDK and OpenAI Agents SDK with TypeScript. Set your Superserve API key.

```bash
npm install @superserve/sdk @openai/agents zod
export SUPERSERVE_API_KEY=ss_live_...
```

--------------------------------

### Python Quick Start Execution

Source: https://github.com/superserve-ai/superserve/blob/main/recipes/claude/research-agent/README.md

Commands to build the sandbox template, create the agent, and run the orchestrator for the Python implementation. The orchestrator is designed for long-running execution.

```bash
uv run build_template.py         # one-time
uv run create_agent.py my-agent  # one-time
uv run orchestrator.py           # long-running
```

--------------------------------

### Install and Run Codex via npm

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/coding-agents/codex.mdx

Install the OpenAI Codex CLI globally using npm and then run the codex command in a Superserve sandbox terminal.

```bash
npm install -g @openai/codex && codex
```

--------------------------------

### Create and Seed a Pre-prepared Sandbox (Python)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/managed-agents/claude-managed-agents.mdx

This Python code demonstrates how to create a sandbox from a template, write custom data, clone a repository, and initiate a session using the pre-prepared sandbox's ID.

```python
from superserve import Sandbox

sandbox = Sandbox.create(
    name="prepped-session",
    from_template="claude-managed-agent",
)
sandbox.files.write("/workspace/data.csv", data_contents)
sandbox.commands.run("git clone https://github.com/org/repo /workspace/repo")

session = client.beta.sessions.create(
    agent=agent_id,
    environment_id=environment_id,
    metadata={"superserve.sandbox_id": sandbox.id},
)
```

--------------------------------

### TypeScript Quick Start: Run Orchestrator

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to start the orchestrator script using TypeScript. This script continuously polls the work queue and manages agent execution.

```bash
node orchestrator.mjs
```

--------------------------------

### Create and Connect to a Sandbox

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-design.md

Demonstrates how to create a new sandbox with various configuration options or connect to an existing one. Use `create` for new sandboxes and `connect` for existing ones.

```typescript
import { Sandbox } from "@superserve/sdk"

// Create a new sandbox
const sandbox = await Sandbox.create({
  name: "my-sandbox",               // required
  fromSnapshot?: "snapshot-uuid",    // optional: boot from snapshot
  timeoutSeconds?: 3600,            // optional: hard lifetime cap
  metadata?: { env: "prod" },       // optional: string-to-string tags
  envVars?: { API_KEY: "..." },     // optional: injected into all processes
  network?: {                       // optional: egress rules
    allowOut: ["api.openai.com"],
    denyOut: ["0.0.0.0/0"],
  },
  // Auth (optional — falls back to SUPERSERVE_API_KEY env var)
  apiKey?: "ss_live_...",
  baseUrl?: "https://api.superserve.ai",
})

// Connect to an existing sandbox (fetches info + access_token)
const sandbox = await Sandbox.connect(sandboxId, { apiKey?, baseUrl? })
```

--------------------------------

### Python Quick Start: Run Orchestrator

Source: https://github.com/superserve-ai/superserve/blob/main/guides/claude/claude-managed-agents/README.md

Command to start the orchestrator script using Python. This script continuously polls the work queue and manages agent execution.

```bash
uv run orchestrator.py
```

--------------------------------

### Create and Configure Opencode Sandbox with Python SDK

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/coding-agents/opencode.mdx

Create a Superserve sandbox using the Python SDK, specifying the template and environment variables. It then installs Opencode and configures the bashrc file.

```python
from superserve import Sandbox

sandbox = Sandbox.create(
    name="opencode",
    from_template="superserve/node-22",
    env_vars={"ANTHROPIC_API_KEY": "sk-ant-..."},
)

sandbox.commands.run("curl -fsSL https://opencode.ai/install | bash")
sandbox.commands.run("echo 'export PATH=/home/user/.opencode/bin:$PATH' >> ~/.bashrc")
```

--------------------------------

### Install Dependencies (Python)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/agent-harnesses/claude-agent-sdk.mdx

Install the required libraries for integrating the Claude Agent SDK with Superserve in a Python project. Set your Superserve API key as an environment variable.

```bash
pip install superserve claude-agent-sdk
export SUPERSERVE_API_KEY=ss_live_...
```

--------------------------------

### Create a Sandbox with Options

Source: https://github.com/superserve-ai/superserve/blob/main/docs/sandbox/create.mdx

Configure sandbox creation with metadata, environment variables, timeout, and network egress rules.

```typescript
import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "data-analyzer",
  timeoutSeconds: 3600,
  metadata: { env: "prod", owner: "agent-7" },
  envVars: { OPENAI_API_KEY: "sk-..." },
  network: {
    allowOut: ["api.openai.com", "*.github.com"],
    denyOut: ["0.0.0.0/0"],
  },
})
```

```python
from superserve import Sandbox, NetworkConfig

sandbox = Sandbox.create(
    name="data-analyzer",
    timeout_seconds=3600,
    metadata={"env": "prod", "owner": "agent-7"},
    env_vars={"OPENAI_API_KEY": "sk-..."},
    network=NetworkConfig(
        allow_out=["api.openai.com", "*.github.com"],
        deny_out=["0.0.0.0/0"],
    ),
)
```

--------------------------------

### Read Files from Sandbox

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-design.md

Read file content from the sandbox. Use `read` to get content as a `Uint8Array` or `readText` to get it as a string. Useful for configuration files or binary assets.

```typescript
// Read a file
const content: Uint8Array = await sandbox.files.read("/app/config.json")
const text: string = await sandbox.files.readText("/app/config.json")
```

--------------------------------

### Create Sandbox from Template (Python)

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-24-templates-sdk-docs-plan.md

Demonstrates creating a sandbox using either a template instance or its alias in Python.

```python
from superserve import Sandbox

# Option 1: pass the Template instance

sandbox = Sandbox.create(name="run-1", from_template=template)

# Option 2: pass the alias
sandbox2 = Sandbox.create(name="run-2", from_template="my-python-env")
```

--------------------------------

### Sandbox Creation

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-design.md

Demonstrates how to create a new Superserve sandbox with various optional configurations.

```APIDOC
## Sandbox.create()

### Description
Creates a new Superserve sandbox. This is a class method.

### Method
`Sandbox.create()`

### Parameters
- **name** (str) - Required - The name for the new sandbox.
- **from_snapshot** (str) - Optional - The ID of a snapshot to create the sandbox from.
- **timeout_seconds** (int) - Optional - The maximum time in seconds the sandbox will run before being terminated.
- **metadata** (dict) - Optional - A dictionary of key-value pairs for metadata.
- **env_vars** (dict) - Optional - Environment variables to set within the sandbox.
- **api_key** (str) - Optional - The API key for authentication. Falls back to environment variable `SS_API_KEY`.
- **base_url** (str) - Optional - The base URL for the Superserve API. Defaults to `https://api.superserve.ai`.

### Request Example
```python
from superserve import Sandbox

sandbox = Sandbox.create(
    name="my-sandbox",
    from_snapshot="snapshot-uuid",       # optional
    timeout_seconds=3600,               # optional
    metadata={"env": "prod"},           # optional
    env_vars={"API_KEY": "..."},        # optional
    api_key="ss_live_...",              # optional, falls back to env var
    base_url="https://api.superserve.ai",  # optional
)
```
```

--------------------------------

### Install Dependencies (TypeScript)

Source: https://github.com/superserve-ai/superserve/blob/main/docs/integrations/agent-harnesses/claude-agent-sdk.mdx

Install the necessary packages for using the Claude Agent SDK with Superserve in a TypeScript environment. Ensure your Superserve API key is set as an environment variable.

```bash
npm install @superserve/sdk @anthropic-ai/claude-agent-sdk zod
export SUPERSERVE_API_KEY=ss_live_...
```

--------------------------------

### Commit Changes to .env.example

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-plan.md

Stages and commits the updated '.env.example' file with a message indicating the API URL change for mock routes.

```bash
cd /Users/nirnejak/Code/superserve/superserve && git add apps/console/.env.example && git commit -m "console: update API URL to point to mock routes in dev"
```

--------------------------------

### GET /sandboxes/[sandbox_id]/files/[...path]

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-04-api-integration-plan.md

Handles GET requests to retrieve a file from a specified path within a sandbox. It validates the API key and sandbox, and prepares to fetch the file content.

```typescript
// apps/console/src/app/api/v1/sandboxes/[sandbox_id]/files/[...path]/route.ts

import {
  NextResponse
} from "next/server"
import { sandboxes } from "../../../../_mock/store"

// Simple in-memory file store
const fileStore = new Map<string, ArrayBuffer>()

function getStoreKey(sandboxId: string, path: string): string {
  return `${sandboxId}:${path}`
}

export async function PUT(
  request: Request,
  { params }: { params: Promise<{ sandbox_id: string; path: string[] }> },
) {
  const apiKey = request.headers.get("X-API-Key")
  if (!apiKey) {
    return NextResponse.json(
      { error: { code: "unauthorized", message: "Missing API key" } },
      { status: 401 },
    )
  }

  const { sandbox_id, path } = await params
  const sandbox = sandboxes.find(
    (s) => s.id === sandbox_id && s.status !== "deleted",
  )

  if (!sandbox) {
    return NextResponse.json(
      { error: { code: "not_found", message: "Sandbox not found" } },
      { status: 404 },
    )
  }

  const filePath = path.join("/")
  const buffer = await request.arrayBuffer()
  fileStore.set(getStoreKey(sandbox_id, filePath), buffer)

  return NextResponse.json({ path: filePath, size: buffer.byteLength })
}

export async function GET(
  request: Request,
  { params }: { params: Promise<{ sandbox_id: string; path: string[] }> },
) {
  const apiKey = request.headers.get("X-API-Key")
  if (!apiKey) {
    return NextResponse.json(
      { error: { code: "unauthorized", message: "Missing API key" } },
      { status: 401 },
    )
  }

  const { sandbox_id, path } = await params

```

--------------------------------

### Manage Sandboxes Statically

Source: https://github.com/superserve-ai/superserve/blob/main/spec/2026-04-16-sdk-from-scratch-design.md

Provides static methods for managing sandboxes by their ID without needing an instance. Use `list` to get all sandboxes, `get` for a specific sandbox's info, and `kill` to terminate a sandbox.

```typescript
// Static lifecycle (manage by ID, no instance needed)
const sandboxes: SandboxInfo[] = await Sandbox.list({ apiKey?, baseUrl?, metadata? })
const info: SandboxInfo = await Sandbox.get(sandboxId, { apiKey?, baseUrl? })
await Sandbox.kill(sandboxId, { apiKey?, baseUrl? })
```