Superserve

https://docs.superserve.ai
Admin
Superserve provides sandbox infrastructure to run code in isolated cloud environments powered by...
Tokens:126,254
Snippets:936
Trust Score:4.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Mesa and run agent commands (CLI)

Source: https://docs.superserve.ai/storage/mesa

This CLI example shows how to install the Mesa CLI, start Mesa as a background daemon using environment variables for authentication, and then run an agent command within the specified workspace. Ensure MESA_TOKEN is set.

```bash
# Install the Mesa CLI. The installer apt-installs fuse3 as a dependency.
curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes

# Start Mesa as a background daemon. MESA_ORG and MESA_API_KEY are read
# from the environment, never persisted to disk.
MESA_ORG="my-org" MESA_API_KEY="$MESA_TOKEN" mesa mount -d

# Run your agent
cd ~/.local/share/mesa/mnt/my-org/agent-workspace
claude "Implement the feature described in TODO.md"
```

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

### Set up Mesa resources and run agent in Superserve sandbox (Python)

Source: https://docs.superserve.ai/storage/mesa

This Python example demonstrates setting up Mesa resources, creating a scoped access token, installing Mesa within a Superserve sandbox, and running an agent command. Ensure your MESA_API_KEY is set in the environment.

```python
import asyncio
import os

from mesa_sdk import Mesa
from superserve import Sandbox


async def main():
    # --- Outside the sandbox: set up Mesa resources (the Mesa SDK is async) ---
    mesa = Mesa(api_key=os.environ["MESA_API_KEY"])

    # Create a repo (or use an existing one)
    repo = await mesa.repos.create(name="agent-workspace")

    # Sign a scoped, self-expiring access token for the sandbox. Signed locally
    # from your API key with no network call, so your API key never enters the sandbox.
    minted = await mesa.tokens.create(
        scopes=["read", "write"],
        repos=["my-org/agent-workspace"],
        ttl_seconds=3600,  # 1 hour
    )

    # --- Inside the sandbox: install and mount Mesa ---
    sandbox = Sandbox.create(from_template="superserve/base")

    # Install the Mesa CLI. The installer apt-installs fuse3 as a dependency.
    sandbox.commands.run("curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes")

    # Start Mesa as a background daemon. MESA_ORG and MESA_API_KEY are read
    # from the environment, never persisted to disk.
    sandbox.commands.run(
        "mesa mount -d",
        env={"MESA_ORG": "my-org", "MESA_API_KEY": minted.token},
    )

    # --- Run your agent ---
    sandbox.commands.run(
        'cd ~/.local/share/mesa/mnt/my-org/agent-workspace ' 
        '&& claude "Implement the feature described in TODO.md"'
    )


asyncio.run(main())
```

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

### Set up Mesa resources and run agent in Superserve sandbox (TypeScript)

Source: https://docs.superserve.ai/storage/mesa

This TypeScript example demonstrates setting up Mesa resources, creating a scoped access token, installing Mesa within a Superserve sandbox, and running an agent command. Ensure your MESA_API_KEY is set in the environment.

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

const mesa = new Mesa({apiKey: process.env.MESA_API_KEY});

// --- Outside the sandbox: set up Mesa resources ---

// Create a repo (or use an existing one)
const repo = await mesa.repos.create({ name: "agent-workspace" });

// Sign a scoped, self-expiring access token for the sandbox. Signed locally
// from your API key with no network call, so your API key never enters the sandbox.
const { token } = await mesa.tokens.create({
  scopes: ["read", "write"],
  repos: ["my-org/agent-workspace"],
  ttl_seconds: 3600, // 1 hour
});

// --- Inside the sandbox: install and mount Mesa ---

const sandbox = await Sandbox.create({ fromTemplate: "superserve/base" });

// Install the Mesa CLI. The installer apt-installs fuse3 as a dependency.
await sandbox.commands.run(
  "curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes",
);

// Start Mesa as a background daemon. MESA_ORG and MESA_API_KEY are read
// from the environment, never persisted to disk.
await sandbox.commands.run("mesa mount -d", {
  env: {
    MESA_ORG: "my-org",
    MESA_API_KEY: token,
  },
});

// --- Run your agent ---

await sandbox.commands.run(
  'cd ~/.local/share/mesa/mnt/my-org/agent-workspace && claude "Implement the feature described in TODO.md"',
);
```

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

### Install Superserve SDK (npm)

Source: https://docs.superserve.ai/quickstart

Install the Superserve SDK using npm. This is the first step to using the SDK in your project.

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

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

### Execute Command in Sandbox

Source: https://docs.superserve.ai/integrations/mcp

Example of starting a server within a sandbox using `sandbox_exec`. This command starts an HTTP server on port 8000.

```bash
sandbox_exec("python3 -m http.server 8000")
```

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

### Install and Run Opencode via Console

Source: https://docs.superserve.ai/integrations/coding-agents/opencode

Use this command to install Opencode and set up its PATH environment variable in the sandbox terminal.

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

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

### Create Custom Template with Mesa CLI

Source: https://docs.superserve.ai/storage/mesa

Use these examples to create a custom Superserve template with the Mesa CLI pre-installed. This speeds up sandbox startup by avoiding runtime installation.

```typescript
import { Template } from "@superserve/sdk";

const template = await Template.create({
  name: "agent-with-mesa",
  vcpu: 2,
  memoryMib: 2048,
  diskMib: 4096,
  from: "ubuntu:24.04",
  steps: [
    {
      run: "apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/*",
    },
    { run: "curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes" },
  ],
});

await template.waitUntilReady();
```

```python
from superserve import Template, RunStep

template = Template.create(
    name="agent-with-mesa",
    vcpu=2,
    memory_mib=2048,
    disk_mib=4096,
    from_="ubuntu:24.04",
    steps=[
        RunStep(
            run="apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/*"
        ),
        RunStep(run="curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes"),
    ],
)

template.wait_until_ready()
```

```dockerfile
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git \
    && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes
```

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

### Install Superserve SDK (pip)

Source: https://docs.superserve.ai/quickstart

Install the Superserve SDK using pip. This is the first step to using the SDK in your Python project.

```bash
pip install superserve
```

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

### Create Sandbox Request Example

Source: https://docs.superserve.ai/api-reference/sandboxes/create-a-new-sandbox

This example demonstrates how to make a POST request to the /sandboxes endpoint to create a new sandbox. It shows the basic JSON payload required for the request.

```json
{
  "from_template": "superserve/python-3.11"
}
```

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

### Install Superserve SDK and Set API Key

Source: https://docs.superserve.ai/integrations/coding-agents/claude

Install the Superserve SDK and set your API key as an environment variable. This is required before interacting with Superserve services via the SDK.

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

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

### Sandbox Metadata Example

Source: https://docs.superserve.ai/api-reference/sandboxes/partially-update-a-running-sandbox

Example of how to structure metadata for a sandbox, including environment and owner tags. This can be patched regardless of sandbox state.

```yaml
metadata:
  env: prod
  owner: agent-7
```

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

### Install Dependencies (Python)

Source: https://docs.superserve.ai/integrations/agent-harnesses/openai-agents-sdk

Install the necessary packages for using Superserve with the OpenAI Agents SDK in a Python environment. Ensure your SUPERSERVE_API_KEY is exported.

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

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

### Install Dependencies (TypeScript)

Source: https://docs.superserve.ai/integrations/agent-harnesses/openai-agents-sdk

Install the necessary packages for using Superserve with the OpenAI Agents SDK in a TypeScript environment. Ensure your SUPERSERVE_API_KEY is exported.

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

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

### Define Start Command for Build

Source: https://docs.superserve.ai/templates/build-spec

Specifies the command to run after the build process completes. This command is captured as a running process in the snapshot.

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

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

### Network Deny Out Example

Source: https://docs.superserve.ai/api-reference/sandboxes/partially-update-a-running-sandbox

Example of configuring egress network rules to deny all traffic not explicitly allowed. Use '0.0.0.0/0' to block all traffic not in 'allow_out'.

```yaml
deny_out:
  - 0.0.0.0/0
```

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

### Install and Run Codex CLI in Sandbox

Source: https://docs.superserve.ai/integrations/coding-agents/codex

Install the OpenAI Codex CLI globally and then run it within the sandbox terminal. This is typically done after setting up the sandbox environment and binding secrets.

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

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

### Install Archil CLI and Dependencies in Template

Source: https://docs.superserve.ai/storage/archil

Installs the Archil CLI and libfuse2 dependency into a Superserve template. This ensures that sandboxes created from this template are ready to mount Archil filesystems without needing to reinstall on each run.

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

const template = await Template.create({
  name: "archil-base",
  from: "ubuntu:22.04",
  steps: [
    { run: "apt-get update && apt-get install -y curl libfuse2" },
    { run: "curl -fsSL https://archil.com/install | sh" },
  ],
})

await template.waitUntilReady()
```

```python
from superserve import Template, RunStep

template = Template.create(
    name="archil-base",
    from_="ubuntu:22.04",
    steps=[
        RunStep(run="apt-get update && apt-get install -y curl libfuse2"),
        RunStep(run="curl -fsSL https://archil.com/install | sh"),
    ],
)

template.wait_until_ready()
```

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

### Billing and Provider Discovery with SDK

Source: https://docs.superserve.ai/integrations/mcp

Usage data and provider discovery for secret-provider setup are accessible via the SDK, including `Provider.list()`.

```typescript
Provider.list()
```

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

### List Built-in Providers (Python)

Source: https://docs.superserve.ai/sdk-reference/secret

Use `Provider.list()` in Python to get a list of supported provider shortcuts. This helps in identifying available authentication methods and host configurations.

```python
providers = Provider.list()
```

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

### Create a Basic Sandbox

Source: https://docs.superserve.ai/sandbox/create

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

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

### Get Secret Audit Events

Source: https://docs.superserve.ai/sdk-reference/secret

Retrieve audit events for a secret using `getAudit`. You can filter by status and limit the number of events returned. Requires setup for TypeScript.

```typescript
const events = await secret.getAudit({ limit: 50, status: "4xx" })
```

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

### Create Sandbox, Run Command, and Read File (Python)

Source: https://docs.superserve.ai/quickstart

Create a sandbox, run an echo command, write to a file, read the file content, and then terminate the sandbox. Ensure the SDK is installed and the API key is set.

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

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

### Create and Boot a New Sandbox (Python)

Source: https://docs.superserve.ai/sdk-reference/sandbox

Use `Sandbox.create` to initialize a new sandbox with specified configurations like name, timeout, environment variables, and network settings. The sandbox is active upon promise resolution.

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

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

### Start OpenClaw in tmux and Run Gateway

Source: https://docs.superserve.ai/integrations/personal-agents/openclaw

Initiate a new tmux session named 'openclaw' and then run the OpenClaw gateway. This setup ensures OpenClaw continues running even if the terminal is closed.

```bash
tmux new -s openclaw
openclaw gateway run
```

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

### Create Sandbox, Run Command, and Read File (TypeScript)

Source: https://docs.superserve.ai/quickstart

Create a sandbox, run an echo command, write to a file, read the file content, and then terminate the sandbox. Ensure the SDK is installed and the API key is set.

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

const sandbox = await Sandbox.create({ name: "quickstart" })

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

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

await sandbox.kill()
```

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

### Install gcsfuse on Ubuntu Template

Source: https://docs.superserve.ai/storage/cloud-buckets

Installs gcsfuse on an Ubuntu 22.04 template. This involves adding the Google Cloud apt repository and then installing the gcsfuse package.

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

const template = await Template.create({
  name: "gcs-base",
  from: "ubuntu:22.04",
  steps: [
    { run: "apt-get update && apt-get install -y curl gnupg lsb-release" },
    {
      run: 'echo "deb [signed-by=/usr/share/keyrings/cloud.google.asc] https://packages.cloud.google.com/apt gcsfuse-$(lsb_release -c -s) main" > /etc/apt/sources.list.d/gcsfuse.list',
    },
    {
      run: "curl https://packages.cloud.google.com/apt/doc/apt-key.gpg > /usr/share/keyrings/cloud.google.asc",
    },
    { run: "apt-get update && apt-get install -y gcsfuse" },
  ],
})

await template.waitUntilReady()
```

```python
from superserve import Template, RunStep

template = Template.create(
    name="gcs-base",
    from_="ubuntu:22.04",
    steps=[
        RunStep(run="apt-get update && apt-get install -y curl gnupg lsb-release"),
        RunStep(
            run='echo "deb [signed-by=/usr/share/keyrings/cloud.google.asc] https://packages.cloud.google.com/apt gcsfuse-$(lsb_release -c -s) main" > /etc/apt/sources.list.d/gcsfuse.list'
        ),
        RunStep(
            run="curl https://packages.cloud.google.com/apt/doc/apt-key.gpg > /usr/share/keyrings/cloud.google.asc"
        ),
        RunStep(run="apt-get update && apt-get install -y gcsfuse"),
    ],
)

template.wait_until_ready()
```

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

### Create a template and kick off the first build

Source: https://docs.superserve.ai/llms.txt

Creates a new template and initiates its first build. The response includes IDs for both the template and the build, enabling clients to monitor status or stream logs.

```APIDOC
## POST /templates

### Description
Creates a template and queues the first build. The response includes both the template id and the build id, so clients can immediately poll `GET /templates/{id}` for overall status or subscribe to `GET /templates/{id}/builds/{build_id}/logs` for live output.

### Method
POST

### Endpoint
/templates

### Parameters
#### Request Body
- **name** (string) - Required - The name of the template.
- **source_code_url** (string) - Required - The URL of the source code repository.
- **build_args** (object) - Optional - Arguments for the build process.
```

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

### Install s3fs in a TypeScript Template

Source: https://docs.superserve.ai/storage/cloud-buckets

Installs the s3fs-fuse package in a Docker template. This is the first step to enable mounting S3 buckets.

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

const template = await Template.create({
  name: "s3-base",
  from: "ubuntu:22.04",
  steps: [{ run: "apt-get update && apt-get install -y s3fs" }],
})

await template.waitUntilReady()
```

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

### Create a Pre-prepared Sandbox for a Session

Source: https://docs.superserve.ai/integrations/managed-agents/claude-managed-agents

Creates a sandbox, writes data to it, clones a repository, and then starts a session using the sandbox's ID in the metadata. This is useful for sessions requiring custom data loaded beforehand.

```typescript
import { Sandbox } from "@superserve/sdk"
import Anthropic from "@anthropic-ai/sdk"

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

  const session = await client.beta.sessions.create({
    agent: agentId,
    environment_id: environmentId,
    metadata: { "superserve.sandbox_id": sandbox.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},
  )
```

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

### Wire Sandbox into Agent (Python)

Source: https://docs.superserve.ai/integrations/agent-harnesses/openai-agents-sdk

This Python example shows how to set up a Superserve sandbox and define a 'bash' function tool for an OpenAI agent. The agent can then execute shell commands within the isolated sandbox.

```python
import asyncio
from agents import Agent, Runner, function_tool
from superserve import Sandbox

sandbox = Sandbox.create(name="agent-runtime")

@function_tool
def bash(command: str) -> str:
    """Run a shell command in the sandbox."""
    result = sandbox.commands.run(command, timeout_seconds=60)
    return f"{result.stdout}\n{result.stderr}"

agent = Agent(
    name="Workspace Assistant",
    instructions="Use the bash tool to inspect the sandbox before answering.",
    tools=[bash],
)

async def main():
    result = await Runner.run(
        agent,
        "List the files in /tmp and tell me how many there are.",
    )
    print(result.final_output)
    sandbox.kill()

asyncio.run(main())
```

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

### Install s3fs in a Python Template

Source: https://docs.superserve.ai/storage/cloud-buckets

Installs the s3fs-fuse package in a Docker template using Python. This prepares the template for S3 bucket mounting.

```python
from superserve import Template, RunStep

template = Template.create(
    name="s3-base",
    from_="ubuntu:22.04",
    steps=[RunStep(run="apt-get update && apt-get install -y s3fs")],
)

template.wait_until_ready()
```

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

### POST /templates

Source: https://docs.superserve.ai/api-reference/templates/create-a-template-and-kick-off-the-first-build

Creates a new template and queues its first build. This is useful for setting up reproducible environments from scratch.

```APIDOC
## POST /templates

### Description
Creates a new template and queues its first build. This is useful for setting up reproducible environments from scratch.

### Method
POST

### Endpoint
/templates

### Parameters
#### Request Body
- **name** (string) - Required - Human-readable name, unique per team. Used as the `from_template` value when creating sandboxes. Lowercase letters, digits, and `.` `_` `/` `-` only; must start and end with a letter or digit. Names starting with `superserve/` are reserved for curated system templates and rejected for team-owned templates.
- **vcpu** (integer) - Optional - Default: 1 - Minimum: 1, Maximum: 4
- **memory_mib** (integer) - Optional - Default: 1024 - Minimum: 256, Maximum: 4096
- **disk_mib** (integer) - Optional - Default: 4096 - Minimum: 1024, Maximum: 8192
- **build_spec** (object) - Required - Declaration of how to build a template.
  - **from** (string) - Required - OCI image reference for the base. Examples: `python:3.11`, `node:22-slim`, `ghcr.io/myorg/foo:v1`. Resolved to a digest at build time and recorded for reproducibility. Must be a Linux/amd64 image. Alpine and distroless bases are rejected at validation.
    - example: python:3.11
  - **steps** (array) - Optional - Ordered list of build steps executed inside the build VM.
    - items ($ref: '#/components/schemas/BuildStep')
  - **start_cmd** (string) - Optional - Optional command started after build steps complete. The snapshot captures the running process, so sandboxes restored from this template come up with the process already live.
  - **ready_cmd** (string) - Optional - Optional readiness probe. Polled every 2s after `start_cmd`, until it exits 0 or 10 minutes elapse. Use to wait for a server to bind its port before snapshotting.

### Response
#### Success Response (200)
- **id** (string) - UUID
- **team_id** (string) - UUID
- **name** (string)
- **status** (string) - Enum: `building`, `ready`, `failed`
- **vcpu** (integer)
- **memory_mib** (integer)
- **disk_mib** (integer)
- **created_at** (string) - date-time
- **build_id** (string) - UUID - ID of the first build. Use it to stream logs or poll status.

#### Response Example
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "team_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
  "name": "my-python-env",
  "status": "building",
  "vcpu": 1,
  "memory_mib": 1024,
  "disk_mib": 4096,
  "created_at": "2023-10-27T10:00:00Z",
  "build_id": "12345678-90ab-cdef-1234-567890abcdef"
}
```

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

### Create and Boot a New Sandbox

Source: https://docs.superserve.ai/sdk-reference/sandbox

Use `Sandbox.create` to initialize a new sandbox with specified configurations like name, timeout, environment variables, and network settings. The sandbox is active upon promise resolution.

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

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

### Network Allow Out Example

Source: https://docs.superserve.ai/api-reference/sandboxes/partially-update-a-running-sandbox

Example of configuring egress network rules to allow specific domains and CIDRs. Private IP ranges are always blocked.

```yaml
allow_out:
  - api.openai.com
  - '*.github.com'
  - 8.8.8.8/32
```

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

### Create a Python Environment Template

Source: https://docs.superserve.ai/sdk-reference/template

Register a new template with specified configurations for CPU, memory, disk, base image, build steps, start command, and readiness probe. The build runs asynchronously.

```typescript
const template = await Template.create({
    name: "my-python-env",
    vcpu: 2,
    memoryMib: 2048,
    diskMib: 4096,
    from: "python:3.11",
    steps: [
      { run: "pip install numpy pandas" },
      { env: { key: "DEBUG", value: "1" } },
      { workdir: "/app" },
      { user: { name: "appuser", sudo: true } },
    ],
    startCmd: "python server.py",
    readyCmd: "curl -f http://localhost:8080/health",
  })
```

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

### Get Billing Pricing OpenAPI Specification

Source: https://docs.superserve.ai/api-reference/billing/get-billing-pricing

This OpenAPI specification defines the endpoint for retrieving billing pricing. It details the request and response structure for the GET /billing/pricing operation.

```yaml
openapi: 3.1.0
info:
  title: Superserve API
  version: 0.1.0
  description: >
    Superserve provides sandbox infrastructure to run AI agents in the cloud.
    Powered by Firecracker MicroVMs.


    ## Sandbox lifecycle


    ```

    active <--> paused --> deleted

    ```


    A sandbox is `active` when running and `paused` after being paused. Resuming
    a paused sandbox returns it to `active`. Deleting releases all resources.


    | Endpoint | What it does |
    |----------|-------------|
    | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) |
    | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network
    rules) |
    | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM |
    | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it
    left off |
    | `DELETE /sandboxes/:id` | Delete sandbox and all resources |


    ## Sandbox environment


    By default sandboxes boot from the curated `superserve/base` template
    (Ubuntu 24.04,
    1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl,
    and build-essential pre-installed). Callers can override with any template
    name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned
    template UUID
    via the `from_template` field on `POST /sandboxes`.


    ## Files and commands


    `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use
    its `X-Access-Token` (returned by create, resume, and activate), not the
    team API key. Two host forms reach them:


    - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id:
    <sandbox_id>`.

```

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

### Install Claude Agent SDK and Superserve SDK (Python)

Source: https://docs.superserve.ai/integrations/agent-harnesses/claude-agent-sdk

Install the necessary packages for using the Claude Agent SDK with Superserve in a Python project. Ensure your SUPERSERVE_API_KEY is exported.

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

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

### Install Claude Agent SDK and Superserve SDK (TypeScript)

Source: https://docs.superserve.ai/integrations/agent-harnesses/claude-agent-sdk

Install the necessary packages for using the Claude Agent SDK with Superserve in a TypeScript project. Ensure your SUPERSERVE_API_KEY is exported.

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

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

### Create Sandbox with Network Allowlist (Python)

Source: https://docs.superserve.ai/sandbox/networking

Create a sandbox with specific outbound network access using Python. This example denies all outbound traffic by default and then allows access to `api.openai.com`, `*.github.com`, and a specific CIDR block.

```python
from superserve import Sandbox, NetworkConfig

sandbox = Sandbox.create(
    name="restricted",
    network=NetworkConfig(
        allow_out=["api.openai.com", "*.github.com", "140.82.112.0/20"],
        deny_out=["0.0.0.0/0"],
    ),
  )
```

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

### Create a Sandbox from a Template

Source: https://docs.superserve.ai/sandbox/create

Boot a sandbox from a system or team template via `fromTemplate`. The sandbox's vCPU, memory, and disk size are inherited from the template.

```typescript
const sandbox = await Sandbox.create({
  name: "my-sandbox",
  fromTemplate: "superserve/python-3.11",  // name
})
```

```python
sandbox = Sandbox.create(
    name="my-sandbox",
    from_template="superserve/python-3.11",
)
```

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

### Create a Sandbox with Options

Source: https://docs.superserve.ai/sandbox/create

Attach metadata tags, inject environment variables, cap the active lifetime, or lock down network egress at creation time. Use `secrets` for credentials, not `envVars`.

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

const sandbox = await Sandbox.create({
  name: "data-analyzer",
  timeoutSeconds: 3600,
  metadata: { env: "prod", owner: "agent-7" },
  envVars: { LOG_LEVEL: "debug" },
  secrets: { OPENAI_API_KEY: "openai-prod" },
  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={"LOG_LEVEL": "debug"},
    secrets={"OPENAI_API_KEY": "openai-prod"},
    network=NetworkConfig(
        allow_out=["api.openai.com", "*.github.com"],
        deny_out=["0.0.0.0/0"],
    ),
)
```

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

### OpenAPI Specification for Get Sandbox by ID

Source: https://docs.superserve.ai/api-reference/sandboxes/get-a-sandbox-by-id

This OpenAPI snippet defines the GET /sandboxes/{sandbox_id} endpoint, which retrieves a sandbox's details. It includes parameters, responses, and security requirements.

```yaml
openapi: 3.1.0
info:
  title: Superserve API
  version: 0.1.0
  description: >
    Superserve provides sandbox infrastructure to run AI agents in the cloud.
    Powered by Firecracker MicroVMs.


  ## Sandbox lifecycle


  ```

  active <--> paused --> deleted

  ```


  A sandbox is `active` when running and `paused` after being paused. Resuming

  a paused sandbox returns it to `active`. Deleting releases all resources.


  | Endpoint | What it does |
  |----------|-------------|
  | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) |
  | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network
  rules) |
  | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM |
  | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it
  left off |
  | `DELETE /sandboxes/:id` | Delete sandbox and all resources |


  ## Sandbox environment


  By default sandboxes boot from the curated `superserve/base` template
  (Ubuntu 24.04,

  1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl,

  and build-essential pre-installed). Callers can override with any template

  name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned

  template UUID

  via the `from_template` field on `POST /sandboxes`.


  ## Files and commands


  `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use

  its `X-Access-Token` (returned by create, resume, and activate), not the

  team API key. Two host forms reach them:


  - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id: <sandbox_id>`.

  - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header
  needed.
info:
  contact:
    name: Superserve Team
  license:
    name: Proprietary
servers:
  - url: https://api.superserve.ai
    description: Production
security: []
paths:
  /sandboxes/{sandbox_id}:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    get:
      tags:
        - Sandboxes
      summary: Get a sandbox by ID
      operationId: getSandbox
      responses:
        '200':
          description: Sandbox details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey: []
components:
  parameters:
    SandboxId:
      name: sandbox_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique identifier of the sandbox.
  schemas:
    SandboxResponse:
      description: >-
        Single-sandbox shape — `SandboxListItem` plus `access_token` and bound
        secrets.
      allOf:
        - $ref: '#/components/schemas/SandboxListItem'
        - type: object
          properties:
            access_token:
              type: string
              description: |
                Per-sandbox access token for data-plane operations (file
                upload/download, terminal). Pass as the `X-Access-Token`
                header.
            secrets:
              type: array
              description: >
                Credentials bound to this sandbox. Each entry maps an env-var
                name visible to the agent to the secret name it resolves to.
                `revoked=true` when the underlying secret has been soft-deleted
                (the env var still holds the now-useless proxy token).
              items:
                type: object
                required:
                  - env_key
                  - secret_name
                properties:
                  env_key:
                    type: string
                  secret_name:
                    type: string
                  revoked:
                    type: boolean
                    default: false
    SandboxListItem:
      description: Sandbox shape returned by list endpoints.
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - paused
            - resuming
          description: >
            Current state of the sandbox. `active` means running; `paused` means
            paused and awaiting resume. `resuming` is a transient state observed

```

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

### Create a Python Environment Template (Python SDK)

Source: https://docs.superserve.ai/sdk-reference/template

Register a new template using the Python SDK, specifying build parameters like name, resources, base image, and build steps. The build is queued asynchronously.

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

template = Template.create(
    name="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",
)
```

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

### Agent Flow: Spin up sandbox, write script, execute

Source: https://docs.superserve.ai/integrations/mcp

This snippet demonstrates a typical agent workflow for creating a sandbox, writing a Python script to it, and then executing that script. It shows the sequence of MCP calls and their expected outputs.

```text
sandbox_create       { name: "primes" }
                       → { id: "a1b2c3…", name: "primes", status: "active" }

sandbox_files_write  { sandbox_id: "a1b2c3…", path: "/app/primes.py", content: "…" }
                       → { path: "/app/primes.py", bytes: 142 }

sandbox_exec         { sandbox_id: "a1b2c3…", command: "python /app/primes.py" }
                       → { exit_code: 0, stdout: "2 3 5 7 11 13 17 19 23 29", stderr: "" }
```

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

### Get a build by ID

Source: https://docs.superserve.ai/api-reference/templates/get-a-build-by-id

Fetches the details of a specific template build.

```APIDOC
## GET /templates/{template_id}/builds/{build_id}

### Description
Retrieves the details of a specific template build.

### Method
GET

### Endpoint
/templates/{template_id}/builds/{build_id}

### Parameters
#### Path Parameters
- **template_id** (string) - Required - The unique identifier of the template.
- **build_id** (string) - Required - The unique identifier of the template build.

### Responses
#### Success Response (200)
- **id** (string) - The unique identifier of the build.
- **template_id** (string) - The unique identifier of the template.
- **status** (string) - The current status of the build (pending, building, snapshotting, ready, failed, cancelled).
- **build_spec_hash** (string) - Stable hash of the build_spec at submission time.
- **error_message** (string) - Populated when status is 'failed'. Includes a stable error code and message.
- **started_at** (string) - The timestamp when the build started.
- **finalized_at** (string) - The timestamp when the build was finalized.
- **created_at** (string) - The timestamp when the build was created.

#### Error Response (401)
- **error** (object) - Contains error details.
  - **code** (string) - A machine-readable error code.
  - **message** (string) - A human-readable error message.

#### Error Response (404)
- **error** (object) - Contains error details.
  - **code** (string) - A machine-readable error code.
  - **message** (string) - A human-readable error message.

#### Error Response (500)
- **error** (object) - Contains error details.
  - **code** (string) - A machine-readable error code.
  - **message** (string) - A human-readable error message.
```

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

### Get Latest Secret Info

Source: https://docs.superserve.ai/sdk-reference/secret

Re-fetches the latest `SecretInfo` for a given secret.

```typescript
await secret.getInfo()
```

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

### Get a secret's metadata

Source: https://docs.superserve.ai/api-reference/secrets/get-a-secrets-metadata

Returns metadata only — the cleartext value is never returned.

```APIDOC
## GET /secrets/{name}

### Description
Returns metadata only — the cleartext value is never returned.

### Method
GET

### Endpoint
/secrets/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Secret name as set at creation.

### Response
#### Success Response (200)
- **id** (string) - Secret unique identifier.
- **name** (string) - The name of the secret.
- **auth_type** (string) - The type of authentication used by the secret. Possible values: `bearer`, `basic`, `api-key`, `custom`, `per_host`. `per_host` indicates a multi-rule secret; the resolved rules are in `auth_config.per_host`.
- **auth_config** (object) - Resolved auth scheme details (no cleartext value).
- **provider_shortcut** (string) - Provider shortcut used at creation, if any.
- **hosts** (array) - An array of hostnames associated with the secret.
- **created_at** (string) - Timestamp of when the secret was created.
- **updated_at** (string) - Timestamp of when the secret was last updated.
- **last_used_at** (string) - Timestamp of the most recent egress that used this secret.

#### Response Example
{
  "example": "{\"id\": \"01234567-89ab-cdef-0123-456789abcdef\", \"name\": \"my-secret\", \"auth_type\": \"bearer\", \"auth_config\": {\"token\": \"<redacted>\"}, \"hosts\": [\"example.com\"], \"created_at\": \"2023-10-27T10:00:00Z\", \"updated_at\": \"2023-10-27T10:00:00Z\", \"last_used_at\": \"2023-10-27T11:00:00Z\"}"
}

#### Error Response (401)
- **error** (object) - Error details.
  - **code** (string) - Machine-readable error code.
  - **message** (string) - Human-readable error message.

#### Error Response (404)
- **error** (object) - Error details.
  - **code** (string) - Machine-readable error code.
  - **message** (string) - Human-readable error message.

#### Error Response (500)
- **error** (object) - Error details.
  - **code** (string) - Machine-readable error code.
  - **message** (string) - Human-readable error message.
```

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

### Create Sandbox with Network Allowlist

Source: https://docs.superserve.ai/sandbox/networking

Create a sandbox with specific outbound network access. This example denies all outbound traffic by default and then allows access to `api.openai.com`, `*.github.com`, and a specific CIDR block.

```typescript
const sandbox = await Sandbox.create({
    name: "restricted",
    network: {
      allowOut: ["api.openai.com", "*.github.com", "140.82.112.0/20"],
      denyOut: ["0.0.0.0/0"],
    },
  })
```

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

### Create Sandbox Template

Source: https://docs.superserve.ai/integrations/mcp

Illustrates creating a sandbox template. This is used to define the shape (vCPU, memory, disk) and preinstalled software for a sandbox.

```python
sandbox_template_create()
```

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

### Get Template Info

Source: https://docs.superserve.ai/sdk-reference/template

Fetch the current server-side state of the template. This returns a fresh TemplateInfo object.

```typescript
const info = await template.getInfo()
console.log(info.status)  // "pending" | "building" | "ready" | "failed"
```

```python
info = template.get_info()
print(info.status.value)  # "pending" | "building" | "ready" | "failed"
```

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

### List All Secrets

Source: https://docs.superserve.ai/sdk-reference/secret

Get a list of all secrets associated with the current team. This returns an array of SecretInfo objects.

```typescript
const secrets = await Secret.list()
```

```python
secrets = Secret.list()
```

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

### POST /templates

Source: https://docs.superserve.ai/api-reference/templates/create-a-template-and-kick-off-the-first-build

Creates a template and queues the first build. The response includes both the template ID and the build ID, enabling clients to poll for status or subscribe to live build output logs.

```APIDOC
## POST /templates

### Description
Creates a template and queues the first build. The response includes both the template id and the build id, so clients can immediately poll `GET /templates/{id}` for overall status or subscribe to `GET /templates/{id}/builds/{build_id}/logs` for live output.

Template starts in status `building`. Poll until it reaches `ready` before creating sandboxes from it. On failure the status becomes `failed` and `error_message` is populated.

To rebuild an existing template (e.g. after a failure or when the base image updates), use `POST /templates/{id}/builds`.

### Method
POST

### Endpoint
/templates

### Parameters
#### Request Body
- **name** (string) - Required - The name of the template.
- **build_spec** (object) - Required - The specification for building the template.

### Responses
#### Success Response (202)
- **id** (string) - The ID of the created template.
- **build_id** (string) - The ID of the initial build.

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **409** - Conflict
- **429** - Quota Reached (e.g., too many builds, too many templates)
- **500** - Internal Server Error
```

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

### Get a build by ID

Source: https://docs.superserve.ai/api-reference/templates/get-a-build-by-id

Fetches the details of a specific build for a given template ID and build ID.

```APIDOC
## GET /templates/{template_id}/builds/{build_id}

### Description
Retrieves the details of a specific build, identified by its unique build ID, within a given template.

### Method
GET

### Endpoint
/templates/{template_id}/builds/{build_id}

### Parameters
#### Path Parameters
- **template_id** (string) - Required - The unique identifier for the template.
- **build_id** (string) - Required - The unique identifier for the build.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the build.
- **template_id** (string) - The identifier of the template this build belongs to.
- **status** (string) - The current status of the build (e.g., 'pending', 'running', 'completed', 'failed').
- **created_at** (string) - The timestamp when the build was created.
- **completed_at** (string) - The timestamp when the build was completed (if applicable).
- **logs** (string) - A URL to access the build logs.
```
Tokens:
Raw