### Install SDK and Set API Key

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

Install the Superserve SDK and set your API key as an environment variable. This is a prerequisite for using the SDK.

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

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

### Mesa Setup and Agent Execution in Superserve Sandbox (Python)

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

This snippet demonstrates the complete workflow for setting up Mesa within a Superserve sandbox using Python. It covers creating Mesa resources, signing access tokens, installing the Mesa CLI, mounting Mesa, and running an agent command.

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

```

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

### Mesa CLI Commands for Sandbox Setup and Agent Execution

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

This snippet shows the equivalent Mesa CLI commands for setting up Mesa within a sandbox and running an agent. It includes installing the CLI, mounting Mesa with environment variables, and executing an agent command.

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

```

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

### Mesa Setup and Agent Execution in Superserve Sandbox (TypeScript)

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

This snippet demonstrates the complete workflow for setting up Mesa within a Superserve sandbox using TypeScript. It covers creating Mesa resources, signing access tokens, installing the Mesa CLI, mounting Mesa, and running an agent command.

```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"',
);

```

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

### Bake Archil Client into Template (Python)

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

Installs the Archil CLI and libfuse2 dependency into a Superserve template using Python. This ensures sandboxes start with the necessary tools to mount Archil disks.

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

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

### Create Sandbox Request Example

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

This example demonstrates how to create a new sandbox. By default, it uses the 'superserve/base' template. The response includes details of the created sandbox, such as its ID and access token.

```json
{
  "from_template": "superserve/base"
}
```

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

### Install Superserve SDK with npm

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

Install the Superserve SDK using npm for Node.js projects.

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

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

### Install and Run Opencode via Console

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

Execute these commands in the Superserve sandbox terminal to install and set up Opencode. Ensure the ANTHROPIC_API_KEY is bound in advanced options.

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

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

### Install Superserve SDK with pip

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

Install the Superserve SDK using pip for Python projects.

```bash
pip install superserve
```

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

### Create Sandbox from Template and Run Mesa Mount

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

Reference a custom template when creating a sandbox to skip the runtime install step. This example shows how to mount Mesa with organization and API key environment variables.

```typescript
const sandbox = await Sandbox.create({ fromTemplate: "agent-with-mesa" });

await sandbox.commands.run("mesa mount -d", {
  env: {
    MESA_ORG: "my-org",
    MESA_API_KEY: token,
  },
});
```

```python
sandbox = Sandbox.create(from_template="agent-with-mesa")

sandbox.commands.run(
    "mesa mount -d",
    env={"MESA_ORG": "my-org", "MESA_API_KEY": minted.token},
)
```

```bash
MESA_ORG="my-org" MESA_API_KEY="$MESA_TOKEN" mesa mount -d
```

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

### Bake Archil Client into Template (TypeScript)

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

Installs the Archil CLI and libfuse2 dependency into a Superserve template. This ensures sandboxes start with the necessary tools to mount Archil disks.

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

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

### Define process to start after build

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

Use `startCmd` to specify the command that should run after a build is complete. This is useful for starting servers or other background processes.

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

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

### Install Dependencies for TypeScript

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

Install the necessary SDKs and libraries for TypeScript development. Ensure your Superserve API key is exported as an environment variable.

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

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

### 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, allowing clients to immediately poll GET /templates/{id} for overall status or subscribe to GET /templates/{id}/builds/{build_id}/logs for live output.

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

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

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

#### Response Example
```json
{
  "id": "tpl_abc123",
  "build_id": "bld_xyz789"
}
```

#### Error Responses
- **400**: Bad Request
- **401**: Unauthorized
- **409**: Conflict
- **429**: Quota Reached (too_many_builds, too_many_templates)
- **500**: Internal Server Error
```

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

### Install Dependencies (Python)

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

Install the required Python packages for integrating Superserve with OpenAI Agents. Set your Superserve API key as an environment variable.

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

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

### Install Dependencies for Python

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

Install the required Python packages for using the Claude Agent SDK with Superserve. Set your Superserve API key as an environment variable.

```bash
pip install superserve claude-agent-sdk
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 SDK with OpenAI Agents in a TypeScript environment. Ensure your Superserve API key is exported as an environment variable.

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

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

### Install gcsfuse on Ubuntu Template

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

Installs gcsfuse on an Ubuntu 22.04 template. This setup is required before mounting GCS buckets in a sandbox. Ensure you have the necessary permissions and a service account key.

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

```

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

### Executing a Command and Previewing a Port

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

This snippet demonstrates how to start a server within a sandbox using `sandbox_exec` and then obtain a public URL for that server using `sandbox_preview_url`. Any process bound to a port will be reachable via a generated URL.

```bash
# Start a server in the sandbox (e.g., python3 -m http.server 8000)
sandbox_exec("python3 -m http.server 8000")

# Get its public URL
sandbox_preview_url()
```

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

### Create Sandbox, Run Command, and Manage Files (Python)

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

Create a sandbox, execute a command, write to a file, read from a file, and then terminate the sandbox using the Superserve SDK.

```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 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, allowing clients to monitor status or 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

### 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.
```

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

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

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

Creates a sandbox from a template, writes data to it, clones a repository, and then starts a session using the sandbox ID in metadata. Requires agent_id and environment_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},
)
```

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

### Sandbox.create

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

Create and boot a new sandbox. The promise resolves when the VM is active.

```APIDOC
## Sandbox.create

### Description
Create and boot a new sandbox. Synchronous - when the promise resolves, the VM is `active`.

### Method
`Sandbox.create(options)`

### Parameters
#### Options
- **name** (string) - Required - Human-readable sandbox name.
- **fromTemplate** / **from_template** (string | Template) - Optional - Template name, UUID, or `Template` instance to boot from. Defaults to `superserve/base`.
- **fromSnapshot** / **from_snapshot** (string) - Optional - Snapshot UUID to boot from.
- **timeoutSeconds** / **timeout_seconds** (number) - Optional - Max active lifetime before auto-pause. API-side upper bound (subject to change).
- **metadata** (Record<string, string>) - Optional - String tags.
- **envVars** / **env_vars** (Record<string, string>) - Optional - Env vars injected into every process.
- **secrets** (Record<string, string>) - Optional - Bind secrets to env vars (`ENV_VAR → secret name`). The agent sees a stand-in token; the real credential is attached to outbound requests. See [Secrets](/secrets/overview).
- **network** (NetworkConfig) - Optional - Egress allow/deny rules.
- **apiKey** / **api_key** (string) - Optional - Overrides `SUPERSERVE_API_KEY`.
- **baseUrl** / **base_url** (string) - Optional - Overrides `SUPERSERVE_BASE_URL`.
- **signal** (AbortSignal) - Optional - TypeScript only - abort the creation request.

### Request Example
```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"] },
});
```

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

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

### Create and Boot a New Sandbox

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

Use Sandbox.create to initialize a new sandbox. The promise resolves when the VM is active. Configure options like name, timeout, environment variables, and network egress rules.

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

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

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

### Install s3fs in a Template (Python)

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

Installs the s3fs package in a Docker template. This is a prerequisite for mounting S3 buckets.

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

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

### Install s3fs in a Template (TypeScript)

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

Installs the s3fs package in a Docker template. This is a prerequisite for 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()
```

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

### Wire Sandbox into Agent (Python)

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

This Python example shows how to set up a Superserve sandbox, define a 'bash' tool for executing commands in the sandbox, and integrate it with the Claude Agent SDK. It includes setting up options for MCP servers and handling agent responses.

```python
import anyio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, create_sdk_mcp_server, tool
from superserve import AsyncSandbox

sandbox: AsyncSandbox | None = None

@tool("bash", "Run a shell command in the sandbox.", {"command": str})
async def bash(args):
    result = await sandbox.commands.run(args["command"], timeout_seconds=60)
    return {
        "content": [
            {"type": "text", "text": f"{result.stdout}\n{result.stderr}"},
        ],
    }

superserve = create_sdk_mcp_server(name="superserve", version="1.0.0", tools=[bash])

options = ClaudeAgentOptions(
    mcp_servers={"superserve": superserve},
    allowed_tools=["mcp__superserve__bash"],
)

async def main():
    global sandbox
    sandbox = await AsyncSandbox.create(name="agent-runtime")
    async with ClaudeSDKClient(options=options) as client:
        await client.query("List the files in /tmp and tell me how many there are.")
        async for msg in client.receive_response():
            print(msg)
    await sandbox.kill()

anyio.run(main)
```

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

### Get Template Info (Python)

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

Fetches the current server-side state of a template. Use this to get a snapshot of the template's properties and status.

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

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

### Get Template Info (TypeScript)

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

Fetches the current server-side state of a template. Use this to get a snapshot of the template's properties and status.

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

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

### Create Sandbox, Run Command, and Manage Files (TypeScript)

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

Create a sandbox, execute a command, write to a file, read from a file, and then terminate the sandbox using the Superserve SDK.

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

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

### Agent Flow: Spin up sandbox, write script, and run

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

Demonstrates a typical agent workflow for creating a sandbox, writing a Python script to print prime numbers, and executing it. The output shows the sequence of tool calls and their results.

```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: "" }
```

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

### Install and Run Codex via Console

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

Install the OpenAI Codex CLI globally and launch it in a Superserve sandbox terminal. This is for direct command-line usage.

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

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

### Wire Sandbox into Agent (TypeScript)

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

This TypeScript example demonstrates how to create a Superserve sandbox, define a 'bash' tool that runs commands within the sandbox, and integrate it with the Claude Agent SDK for agent queries. It shows how to send a prompt and process the results.

```typescript
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"
import { Sandbox } from "@superserve/sdk"
import { z } from "zod"

const sandbox = await Sandbox.create({ name: "agent-runtime" })

const bash = tool(
  "bash",
  "Run a shell command in the sandbox.",
  { command: z.string() },
  async ({ command }) => {
    const result = await sandbox.commands.run(command, { timeoutMs: 60_000 })
    return {
      content: [
        { type: "text", text: `${result.stdout}\n${result.stderr}` },
      ],
    }
  },
)

const superserve = createSdkMcpServer({
  name: "superserve",
  version: "1.0.0",
  tools: [bash],
})

for await (const message of query({
  prompt: "List the files in /tmp and tell me how many there are.",
  options: {
    mcpServers: { superserve },
    allowedTools: ["mcp__superserve__bash"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result)
  }
}

await sandbox.kill()
```

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

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

```

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

### Get Billing Pricing OpenAPI Specification

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

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

```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>`.

```

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

### Start Hermes in tmux

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

Start the Hermes agent in a detached tmux session named 'hermes' to ensure it continues running even after closing the terminal or browser tab.

```bash
tmux new -d -s hermes 'hermes gateway'
```

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

### Create Sandbox from 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",
)

```

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

### OpenAPI Specification for Get Template by ID

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

This OpenAPI snippet defines the `GET /templates/{template_id}` endpoint, which is used to retrieve a specific template by its ID. It outlines the request parameters and expected responses.

```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>`.

paths:
  /templates/{template_id}:
    get:
      summary: Get a template by ID
      description: >
        Returns the template with the given ID. Templates are immutable.
      operationId: get_template_by_id
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the template to retrieve.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Template:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the template.
        name:
          type: string
          description: The name of the template.
        description:
          type: string
          description: A brief description of the template.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the template was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the template was last updated.
    Error:
      type: object
      properties:
        message:
          type: string
          description: A message describing the error.
        code:
          type: string
          description: An error code.

```

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

### POST /exec

Source: https://docs.superserve.ai/api-reference/exec/run-a-command-and-wait-for-it-to-finish

Runs a command to completion and returns its full output in a single response. For live output, use `POST /exec/stream` (Server-Sent Events) or `GET /exec/connect` (WebSocket). A non-zero exit code is returned in the body, not as an HTTP error. The sandbox must be `running`; a paused sandbox returns `503`. Activate it first with `POST /sandboxes/{sandbox_id}/activate`.

```APIDOC
## POST /exec

### Description
Runs a command to completion and returns its full output in a single response. For live output use `POST /exec/stream` (Server-Sent Events) or `GET /exec/connect` (WebSocket). A non-zero exit code is returned in the body, not as an HTTP error. The sandbox must be `running`; a paused sandbox returns `503`. Activate it first with `POST /sandboxes/{sandbox_id}/activate`.

### Method
POST

### Endpoint
https://sandbox.superserve.ai/exec or https://boxd-{sandbox_id}.sandbox.superserve.ai/exec

### Parameters
#### Header Parameters
- **X-Superserve-Sandbox-Id** (string) - Required - The sandbox ID (for the shared host).
- **X-Access-Token** (string) - Required - The access token for the sandbox.

#### Request Body
- **command** (string) - Required - The command to execute.
- **args** (array of strings) - Optional - Arguments for the command.

### Request Example
```json
{
  "command": "ls",
  "args": ["-l", "/"]
}
```

### Response
#### Success Response (200)
- **stdout** (string) - The standard output of the command.
- **stderr** (string) - The standard error of the command.
- **exit_code** (integer) - The exit code of the command.

#### Response Example
```json
{
  "stdout": "total 0\n-rw-r--r-- 1 root root 0 Jan 1 00:00 file.txt\n",
  "stderr": "",
  "exit_code": 0
}
```
```

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

### OpenAPI Specification for Get Secret Metadata

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

This OpenAPI snippet defines the GET /secrets/{name} endpoint, which is used to retrieve metadata for a secret. It specifies the path parameter 'name' and indicates that the response will contain secret metadata.

```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>`.

paths:
  /secrets/{name}:
    get:
      summary: Get a secret's metadata
      description: Returns metadata only — the cleartext value is never returned.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Secret metadata retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: The name of the secret.
                  created_at:
                    type: string
                    format: date-time
                    description: The timestamp when the secret was created.
                  updated_at:
                    type: string
                    format: date-time
                    description: The timestamp when the secret was last updated.
                  description:
                    type: string
                    description: An optional description for the secret.
                  tags:
                    type: array
                    items:
                      type: string
                    description: A list of tags associated with the secret.
        "404":
          description: Secret not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Secret not found
        "401":
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized

```

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

### Create Sandbox

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

Creates a new sandbox environment with specified configurations.

```APIDOC
## POST /sandboxes

### Description
Creates a new sandbox environment.

### Method
POST

### Endpoint
/sandboxes

### Parameters
#### Request Body
- **name** (string) - Required - Human-readable name for the sandbox.
- **from_template** (string) - Optional - Boot the sandbox from a template. Accepts either a template UUID or a name (e.g. `superserve/base`, `superserve/python-3.11`, `superserve/node-22`, or a team-owned name like `my-python-env`). The template must be owned by the caller's team OR be a curated system template (curated templates use the `superserve/` name prefix). The template's vCPU, memory, and disk values are inherited by the sandbox — they cannot be overridden per-sandbox because the snapshot dictates VM shape. When omitted, defaults to `superserve/base`.
- **timeout_seconds** (integer) - Optional - Optional hard lifetime cap in seconds, measured from sandbox creation. When set, the sandbox is destroyed this many seconds after creation regardless of state (active, paused) or activity — the user asked for a hard deadline. When unset, the sandbox lives until explicitly paused or deleted. Maximum 604800 (7 days).
- **metadata** (object) - Optional - Flat string-to-string tags attached to the sandbox at creation. Useful for grouping, owner labels, environment, run IDs, etc. Constraints: Strings only. Values must be strings. There is no type coercion: `metadata.count=42` filters for the *string* "42". At most 64 keys. Each key may be at most 256 bytes. Each value may be at most 2048 bytes (2 KB). The serialized object may be at most 16384 bytes (16 KB) in total. Keys starting with `superserve.` or `_superserve` (case-insensitive) are reserved for platform use and rejected. Metadata can be updated after creation via `PATCH /sandboxes/:id`. Filter sandboxes by metadata via the `metadata.{key}` query parameter on `GET /sandboxes`.
- **env_vars** (object) - Optional - Environment variables injected into every process inside the sandbox (terminal sessions, exec calls). Merged on top of any defaults set by the template's `env` build steps — caller keys win on conflict. Survive pause/resume.
- **network** (object) - Optional - Network configuration for the sandbox.
- **secrets** (object) - Optional - Bind team-stored credentials to environment variables inside the sandbox. Keys are env-var names; values are secret names from `POST /secrets`. The agent never sees the real value: it sees a proxy token in env, and the in-host enforcement daemon swaps the token for the real credential at egress.

### Response
#### Success Response (200)
- **access_token** (string) - Per-sandbox access token for data-plane operations (file upload/download, terminal). Pass as the `X-Access-Token` header.
- **secrets** (array) - Credentials bound to this sandbox. Each entry maps an env-var name visible to the agent to the secret name it resolves to.

### Errors
- **400** - `too_many_sandboxes` — team has reached its sandbox count limit (paused sandboxes count toward this cap; only DELETE frees a slot); delete existing sandboxes or contact support to raise the cap.
- **500** - Internal Server Error
```