### Install and Start Redis

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs the redis-server package and starts the Redis server in the foreground. Requires root privileges for apt-get.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "redis-server"],
});

const proc = await sdk.createProcess({
  command: "redis-server",
  args: ["--daemonize", "no"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","redis-server"]}'

curl -X POST "http://127.0.0.1:2468/v1/processes" \
  -H "Content-Type: application/json" \
  -d '{"command":"redis-server","args":["--daemonize","no"]}'
```

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

### Install and Start PostgreSQL

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs PostgreSQL and its client, then starts the PostgreSQL service using pg_ctlcluster. Requires root privileges for apt-get.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "postgresql", "postgresql-client"],
});

// Start the service
const proc = await sdk.createProcess({
  command: "bash",
  args: ["-c", "su - postgres -c \'pg_ctlcluster 15 main start\'"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","postgresql","postgresql-client"]}'
```

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

### Install Dependencies and Build Foundry

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/README.md

Installs Bun, then installs project dependencies using pnpm, and finally builds the project.

```bash
curl -fsSL https://bun.sh/install | bash
pnpm install
pnpm -w build
```

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

### Start Sandbox Agent

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/examples/CLAUDE.md

Use this command to start the Sandbox Agent in development mode. Ensure pnpm is installed.

```bash
SANDBOX_AGENT_DEV=1 pnpm start
```

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

### Start Local Production-Build Preview

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/CLAUDE.md

Starts a local preview of the production build.

```bash
just foundry-preview
```

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

### Install and Run VS Code (code-server)

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs VS Code server via a script and then starts the code-server process. The server binds to all interfaces on port 8080 with no authentication.

```TypeScript
await sdk.runProcess({
  command: "bash",
  args: ["-c", "curl -fsSL https://code-server.dev/install.sh | sh"],
});

const proc = await sdk.createProcess({
  command: "code-server",
  args: ["--bind-addr", "0.0.0.0:8080", "--auth", "none"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"bash","args":["-c","curl -fsSL https://code-server.dev/install.sh | sh"]}'

curl -X POST "http://127.0.0.1:2468/v1/processes" \
  -H "Content-Type: application/json" \
  -d '{"command":"code-server","args":["--bind-addr","0.0.0.0:8080","--auth","none"]}'
```

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

### Start Development Server

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/examples/cloudflare/README.md

Execute this command to start the local development server for the sandbox agent.

```bash
pnpm run dev
```

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

### Full Example: TerminalPane with ProcessTerminal

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/react-components.mdx

This example demonstrates connecting to a Sandbox Agent server, starting an interactive tty shell, rendering it using ProcessTerminal, and cleaning up resources on unmount. Ensure the Sandbox Agent server is running at http://127.0.0.1:2468.

```tsx
"use client";

import { useEffect, useState } from "react";
import { SandboxAgent } from "sandbox-agent";
import { ProcessTerminal } from "@sandbox-agent/react";

export default function TerminalPane() {
  const [client, setClient] = useState<SandboxAgent | null>(null);
  const [processId, setProcessId] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    let cancelled = false;
    let sdk: SandboxAgent | null = null;
    let createdProcessId: string | null = null;

    const cleanup = async () => {
      if (!sdk || !createdProcessId) {
        return;
      }

      await sdk.killProcess(createdProcessId, { waitMs: 1_000 }).catch(() => {});
      await sdk.deleteProcess(createdProcessId).catch(() => {});
    };

    const start = async () => {
      try {
        sdk = await SandboxAgent.connect({
          baseUrl: "http://127.0.0.1:2468",
        });

        const process = await sdk.createProcess({
          command: "sh",
          interactive: true,
          tty: true,
        });

        if (cancelled) {
          createdProcessId = process.id;
          await cleanup();
          await sdk.dispose();
          return;
        }

        createdProcessId = process.id;
        setClient(sdk);
        setProcessId(process.id);
      } catch (err) {
        const message = err instanceof Error ? err.message : "Failed to start terminal.";
        setError(message);
      }
    };

    void start();

    return () => {
      cancelled = true;
      void cleanup();
      void sdk?.dispose();
    };
  }, []);

  if (error) {
    return <div>{error}</div>;
  }

  if (!client || !processId) {
    return <div>Starting terminal...</div>;
  }

  return <ProcessTerminal client={client} processId={processId} height={480} />;
}

```

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

### Start Frontend Locally

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/CLAUDE.md

Starts the frontend service locally using pnpm.

```bash
pnpm --filter @sandbox-agent/foundry-frontend dev
```

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

### Start Sandbox Agent with E2B Provider

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/e2b.mdx

Initialize and start the Sandbox Agent using the E2B provider, configuring environment variables and sandbox templates. This example demonstrates starting an agent with Claude and prompting it.

```typescript
import { SandboxAgent } from "sandbox-agent";
import { e2b } from "sandbox-agent/e2b";

const envs: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) envs.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const template = process.env.E2B_TEMPLATE;

const sdk = await SandboxAgent.start({
  sandbox: e2b({
    template,
    create: { envs },
  }),
});

try {
  const session = await sdk.createSession({ agent: "claude" });
  const response = await session.prompt([
    { type: "text", text: "Summarize this repository" },
  ]);
  console.log(response.stopReason);
} finally {
  await sdk.destroySandbox();
}
```

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

### Build and Run Sandbox Agent Server

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/research/opencode-tmux-test.md

Builds the sandbox-agent locally and starts the server. Ensure opencode is installed and on PATH. Set SANDBOX_AGENT_LOG_HTTP_HEADERS to 1 to include request headers in logs.

```bash
SANDBOX_AGENT_SKIP_INSPECTOR=1 cargo build -p sandbox-agent
SANDBOX_AGENT_LOG_HTTP_HEADERS=1 ./target/debug/sandbox-agent server \
  --host 127.0.0.1 --port 2468 --token "$TOKEN"
```

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

### Start Sandbox Agent with Daytona Provider

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/daytona.mdx

Initializes the Sandbox Agent using the Daytona provider. This example sets up environment variables for API keys and creates a session with the 'claude' agent to summarize a repository.

```typescript
import { SandboxAgent } from "sandbox-agent";
import { daytona } from "sandbox-agent/daytona";

const envVars: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_KEY;

const sdk = await SandboxAgent.start({
  sandbox: daytona({
    create: { envVars },
  }),
});

try {
  const session = await sdk.createSession({ agent: "claude" });
  const response = await session.prompt([
    { type: "text", text: "Summarize this repository" },
  ]);
  console.log(response.stopReason);
} finally {
  await sdk.destroySandbox();
}
```

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

### Start Backend Locally

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/CLAUDE.md

Starts only the backend service locally.

```bash
just foundry-backend-start
```

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

### Install Node.js and npm

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs Node.js and npm using apt-get. For specific versions, consider using nvm.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "nodejs", "npm"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","nodejs","npm"]}'
```

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

### Start Mock Frontend Locally (No Docker)

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/CLAUDE.md

Starts the mock frontend service locally without using Docker.

```bash
just foundry-dev-mock
```

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

### Install Java (OpenJDK)

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs the default Java Development Kit using apt-get.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "default-jdk"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","default-jdk"]}'
```

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

### Install @sandbox-agent/react

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/react-components.mdx

Install the @sandbox-agent/react package using npm.

```bash
npm install @sandbox-agent/react@0.4.x
```

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

### Install Docker

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs Docker using the official convenience script. Requires root privileges.

```TypeScript
await sdk.runProcess({
  command: "bash",
  args: ["-c", "curl -fsSL https://get.docker.com | sh"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"bash","args":["-c","curl -fsSL https://get.docker.com | sh"]}'
```

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

### Install Project Dependencies

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/CONTRIBUTING.md

Install all project dependencies using pnpm. This command should be run after cloning the repository.

```bash
pnpm install
```

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

### Start and Stop Virtual Desktop

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/computer-use.mdx

Connect to the Sandbox Agent and start a virtual desktop session. All fields in the start request are optional; defaults are 1440x900 at 96 DPI. Stop the desktop when finished.

```typescript
import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

const status = await sdk.startDesktop({
  width: 1920,
  height: 1080,
  dpi: 96,
});

console.log(status.state); // "active"
console.log(status.display); // ":99"

// When done
await sdk.stopDesktop();
```

```bash
curl -X POST "http://127.0.0.1:2468/v1/desktop/start" \
  -H "Content-Type: application/json" \
  -d '{"width":1920,"height":1080,"dpi":96}'

curl -X POST "http://127.0.0.1:2468/v1/desktop/stop"
```

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

### Install Ruby

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs the full Ruby package using apt-get.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "ruby-full"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","ruby-full"]}'
```

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

### Install Sandbox Agent SDK and CLI

Source: https://context7.com/rivet-dev/sandbox-agent/llms.txt

Install the TypeScript SDK using npm. Optionally, install the global CLI or run the server directly using a curl script.

```bash
# TypeScript SDK
npm install sandbox-agent@0.4.x

# CLI (global)
npm install -g @sandbox-agent/cli@0.4.x

# Or run server directly via curl
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```

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

### Install Sandbox Agent and ComputeSDK

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/computesdk.mdx

Install the necessary packages for using the Sandbox Agent with ComputeSDK.

```bash
npm install sandbox-agent@0.4.x computesdk
```

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

### Install VLC Media Player

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs the VLC media player. Requires root privileges for apt-get.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "vlc"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","vlc"]}'
```

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

### Run Image with Desktop API Dependencies

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/docker.mdx

Run the Docker image and install desktop API dependencies within the container before starting the server. This command installs necessary packages, downloads and installs the Sandbox Agent, and then starts the server.

```bash
docker run --rm -p 3000:3000 \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  node:22-bookworm-slim sh -c \
    "apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y curl ca-certificates bash libstdc++6 && \
    rm -rf /var/lib/apt/lists/* && \
    curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh && \
    sandbox-agent install desktop --yes && \
    sandbox-agent server --no-token --host 0.0.0.0 --port 3000"
```

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

### Server Configuration Example

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/research/agents/opencode.md

Illustrates server configuration options, including bind address and advertised host, typically loaded from a config file.

```json
// From config.json
{
  "opencode": {
    "host": "127.0.0.1",        // Bind address
    "advertisedHost": "127.0.0.1" // External address (for tunnels)
  }
}

```

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

### Install Fonts and Update Cache

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/computer-use.mdx

Installs font packages using apt-get or copies custom font files and rebuilds the font cache. Ensure 'feh' is installed before starting the desktop if used for wallpapers.

```typescript
// Install a font package
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "fonts-noto", "fonts-liberation"],
});

// Or copy a custom font file
import fs from "node:fs";

const font = await fs.promises.readFile("./CustomFont.ttf");
await sdk.mkdirFs({ path: "~/.local/state/sandbox-agent/desktop/home/.local/share/fonts" });
await sdk.writeFsFile(
  { path: "~/.local/state/sandbox-agent/desktop/home/.local/share/fonts/CustomFont.ttf" },
  font,
);

// Rebuild the font cache
await sdk.runProcess({ command: "fc-cache", args: ["-fv"] });
```

```curl
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"apt-get","args":["install","-y","fonts-noto","fonts-liberation"]}'

curl -X POST "http://127.0.0.1:2468/v1/fs/mkdir?path=~/.local/state/sandbox-agent/desktop/home/.local/share/fonts"

curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=~/.local/state/sandbox-agent/desktop/home/.local/share/fonts/CustomFont.ttf" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @CustomFont.ttf

curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"fc-cache","args":["-fv"]}'
```

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

### Start and Control Desktop Environment

Source: https://context7.com/rivet-dev/sandbox-agent/llms.txt

Connect to the Sandbox Agent and start a virtual desktop session. Configure resolution and DPI. This is the initial step before performing any desktop automation.

```typescript
import { SandboxAgent } from "sandbox-agent";
import fs from "node:fs";

const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
});

// Start desktop environment
const status = await sdk.startDesktop({
  width: 1920,
  height: 1080,
  dpi: 96,
});
console.log("Desktop state:", status.state, "Display:", status.display);
```

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

### Verify Sandbox Agent Binary Installation

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/troubleshooting.mdx

Check if the sandbox agent binary is installed in the expected directory. This helps diagnose issues where the agent fails to start.

```bash
ls -la ~/.local/share/sandbox-agent/bin/
```

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

### Create and Initialize OpenCode Server and Client

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/research/agents/opencode.md

Example of creating an OpenCode server instance with specified host, port, and logging level, and initializing a client to connect to it.

```typescript
import { createOpencodeServer } from "@opencode-ai/sdk/server";
import { createOpencodeClient } from "@opencode-ai/sdk";

const server = await createOpencodeServer({
  hostname: "127.0.0.1",
  port: 4200,
  config: { logLevel: "DEBUG" }
});

const client = createOpencodeClient({
  baseUrl: `http://127.0.0.1:${port}`
});

```

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

### Parsed Command Analysis Example

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/research/agents/codex.md

Example of parsed command analysis, detailing actions like reading, writing, or installing packages. This provides semantic understanding of command operations.

```json
{
  "commandActions": [
    { "type": "read", "path": "/src/main.ts" },
    { "type": "write", "path": "/src/utils.ts" },
    { "type": "install", "package": "lodash" }
  ]
}
```

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

### Install All Agents

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/architecture.mdx

Use this command to pre-install all available coding agents. This helps avoid cold-start delays when agents are used for the first time.

```bash
sandbox-agent install-agent --all
```

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

### Live Streaming (WebRTC)

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/computer-use.mdx

APIs to start, stop, and get the status of WebRTC live streaming.

```APIDOC
## POST /v1/desktop/stream/start

### Description
Start WebRTC streaming.

### Method
POST

### Endpoint
/v1/desktop/stream/start

## POST /v1/desktop/stream/stop

### Description
Stop WebRTC streaming.

### Method
POST

### Endpoint
/v1/desktop/stream/stop

## GET /v1/desktop/stream/status

### Description
Get stream status.

### Method
GET

### Endpoint
/v1/desktop/stream/status

## GET /v1/desktop/stream/signaling

### Description
WebSocket endpoint for WebRTC signaling.

### Method
GET

### Endpoint
/v1/desktop/stream/signaling
```

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

### Start Sandbox Agent Server (CLI)

Source: https://context7.com/rivet-dev/sandbox-agent/llms.txt

Use the `sandbox-agent server` command to start the server. Options include disabling tokens, specifying host and port, and enabling authentication with a token.

```bash
# Start server
sandbox-agent server --no-token --host 0.0.0.0 --port 2468

# With authentication
sandbox-agent server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468

```

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

### TypeScript Example for Sandbox Agent with Modal

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/modal.mdx

This example demonstrates starting a Sandbox Agent within a Modal sandbox, creating a session, and interacting with an agent. It handles API key secrets and specifies a base Docker image.

```typescript
import { SandboxAgent } from "sandbox-agent";
import { modal } from "sandbox-agent/modal";

const secrets: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) secrets.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) secrets.OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const baseImage = process.env.MODAL_BASE_IMAGE ?? "node:22-slim";

const sdk = await SandboxAgent.start({
  sandbox: modal({
    image: baseImage,
    create: { secrets },
  }),
});

try {
  const session = await sdk.createSession({ agent: "claude" });
  const response = await session.prompt([
    { type: "text", text: "Summarize this repository" },
  ]);
  console.log(response.stopReason);
} finally {
  await sdk.destroySandbox();
}
```

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

### Start Headless Server

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/research/agents/opencode.md

Initiate OpenCode as a headless server. You can specify a port or attach to an existing server.

```bash
opencode serve

```

```bash
opencode serve --port 4096

```

```bash
opencode attach http://localhost:4096

```

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

### Interact with Desktop API

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/sdk-overview.mdx

This TypeScript code demonstrates how to get desktop status, start the runtime, take screenshots, get display information, control the mouse, perform clicks, type text, press keys, and stop the desktop runtime.

```typescript
const status = await sdk.getDesktopStatus();

if (status.state === "install_required") {
  console.log(status.installCommand);
}
```

```typescript
const started = await sdk.startDesktop({
  width: 1440,
  height: 900,
  dpi: 96,
});
```

```typescript
const screenshot = await sdk.takeDesktopScreenshot();
```

```typescript
const displayInfo = await sdk.getDesktopDisplayInfo();
```

```typescript
await sdk.moveDesktopMouse({ x: 400, y: 300 });
```

```typescript
await sdk.clickDesktop({ x: 400, y: 300, button: "left", clickCount: 1 });
```

```typescript
await sdk.typeDesktopText({ text: "hello world", delayMs: 10 });
```

```typescript
await sdk.pressDesktopKey({ key: "ctrl+l" });
```

```typescript
await sdk.stopDesktop();
```

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

### Manual Server Start and CLI Attach

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/opencode-compatibility.mdx

Start the Sandbox Agent server manually and then attach the OpenCode CLI. This allows for more control over the server process.

```bash
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode
```

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

### Install jq using SDK

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Use the SDK to install the jq command-line JSON processor. Ensure the command is available in the environment.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "jq"],
});
```

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

### Control-plane and HTTP operations

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/sdk-overview.mdx

Perform various control-plane operations including getting health status, listing agents, installing agents, and interacting with the file system.

```typescript
const health = await sdk.getHealth();
const agents = await sdk.listAgents();
await sdk.installAgent("codex", { reinstall: true });

const entries = await sdk.listFsEntries({ path: "." });
const writeResult = await sdk.writeFsFile({ path: "./hello.txt" }, "hello");

console.log(health.status, agents.agents.length, entries.length, writeResult.path);
```

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

### Drizzle Configuration for Per-Actor Database

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/foundry/research/friction/rivet.mdx

Example of a DrizzleKit configuration file for a specific actor's database. This setup allows for per-actor schema and migration management.

```typescript
import { defineConfig } from "@rivetkit/db/drizzle";

export default defineConfig({
  schema: "./src/actors/<actor>/db/schema.ts",
  out: "./src/actors/<actor>/db/drizzle",
  // ... other config
});
```

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

### Start Sandbox-Agent (OpenCode Compat)

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/research/opencode-web-customization.md

Starts the sandbox-agent in OpenCode compatible mode. Ensure to set environment variables and specify host, port, and CORS origins.

```bash
cd /home/nathan/sandbox-agent.feat-opencode-compat
SANDBOX_AGENT_SKIP_INSPECTOR=1 SANDBOX_AGENT_LOG_STDOUT=1 \
  ./target/debug/sandbox-agent server --no-token --host 127.0.0.1 --port 2468 \
  --cors-allow-origin http://127.0.0.1:5173 \
  > /tmp/sandbox-agent-opencode.log 2>&1 &

```

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

### TypeScript Example with Cloudflare Provider

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/cloudflare.mdx

Demonstrates starting the Sandbox Agent using the cloudflare provider for standalone scripts. Ensure you have the necessary API keys set as environment variables.

```typescript
import { SandboxAgent } from "sandbox-agent";
import { cloudflare } from "sandbox-agent/cloudflare";

const sdk = await SandboxAgent.start({
  sandbox: cloudflare(),
});

try {
  const session = await sdk.createSession({ agent: "codex" });
  const response = await session.prompt([
    { type: "text", text: "Summarize this repository" },
  ]);
  console.log(response.stopReason);
} finally {
  await sdk.destroySandbox();
}
```

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

### Run the HTTP server

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/cli.mdx

Starts the sandbox-agent HTTP server. Use --port to specify the binding port.

```bash
sandbox-agent server [OPTIONS]
```

```bash
sandbox-agent server --port 3000
```

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

### TypeScript Integration with dockerode

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/deploy/docker.mdx

Example demonstrating how to programmatically create, start, and connect to a Sandbox Agent Docker container using the `dockerode` library in TypeScript. It configures environment variables and port bindings.

```typescript
import Docker from "dockerode";
import { SandboxAgent } from "sandbox-agent";

const docker = new Docker();
const PORT = 3000;

const container = await docker.createContainer({
  Image: "rivetdev/sandbox-agent:0.4.2-full",
  Cmd: ["server", "--no-token", "--host", "0.0.0.0", "--port", `${PORT}`],
  Env: [
    `ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
    `OPENAI_API_KEY=${process.env.OPENAI_API_KEY}`,
    `CODEX_API_KEY=${process.env.CODEX_API_KEY}`,
  ].filter(Boolean),
  ExposedPorts: { [`${PORT}/tcp`]: {} },
  HostConfig: {
    AutoRemove: true,
    PortBindings: { [`${PORT}/tcp`]: [{ HostPort: `${PORT}` }] },
  },
});

await container.start();

const baseUrl = `http://127.0.0.1:${PORT}`;
const sdk = await SandboxAgent.connect({ baseUrl });

const session = await sdk.createSession({ agent: "codex" });
await session.prompt([{ type: "text", text: "Summarize this repository." }]);
```

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

### Start Sandbox Agent with Authentication

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/opencode-compatibility.mdx

Start the Sandbox Agent server with authentication enabled and attach the OpenCode CLI using the provided token.

```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode --password "$SANDBOX_TOKEN"
```

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

### Install FFmpeg using SDK

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Use the SDK to install FFmpeg, a powerful tool for handling multimedia data. This is essential for video and audio processing.

```TypeScript
await sdk.runProcess({
  command: "apt-get",
  args: ["install", "-y", "ffmpeg"],
});
```

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

### Connect to Sandbox Agent Server

Source: https://context7.com/rivet-dev/sandbox-agent/llms.txt

Connect to a running Sandbox Agent server using its base URL. Supports connecting to remote instances or starting an embedded server locally. Includes an example of checking server health.

```typescript
import { SandboxAgent } from "sandbox-agent";

// Connect to remote server
const sdk = await SandboxAgent.connect({
  baseUrl: "http://127.0.0.1:2468",
  token: process.env.SANDBOX_TOKEN, // Optional auth token
});

// Or start embedded server locally
const localSdk = await SandboxAgent.start();

// Check server health
const health = await sdk.getHealth();
console.log(health.status); // "ok"
```

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

### Run Sandbox Agent Server

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/quickstart.mdx

Starts the sandbox-agent server. Use `--no-token` for local development. Various methods are provided for running the server, including direct binary execution, npx, bunx, global npm/bun installs, and local Node.js/Bun execution using the SDK.

```bash
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```

```bash
npx @sandbox-agent/cli@0.4.x server --no-token --host 0.0.0.0 --port 2468
```

```bash
bunx @sandbox-agent/cli@0.4.x server --no-token --host 0.0.0.0 --port 2468
```

```bash
npm install -g @sandbox-agent/cli@0.4.x
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```

```bash
bun add -g @sandbox-agent/cli@0.4.x
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
bun pm -g trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
```

```bash
npm install sandbox-agent@0.4.x
```

```typescript
import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.start();
```

```bash
bun add sandbox-agent@0.4.x
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
```

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

### Customizing Desktop Environment

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/computer-use.mdx

Instructions and examples for customizing the desktop environment, including window manager configuration and autostart programs.

```APIDOC
## Customizing Window Manager (openbox)

### Description
This section details how to customize the Openbox window manager by providing an `rc.xml` configuration file.

### File Path
`~/.local/state/sandbox-agent/desktop/home/.config/openbox/rc.xml`

### Example Configuration
```xml
<?xml version="1.0" encoding="UTF-8"?>
<openbox_config xmlns="http://openbox.org/3.4/rc">
  <theme>
    <name>Clearlooks</name>
    <titleLayout>NLIMC</titleLayout>
    <font place="ActiveWindow"><name>DejaVu Sans</name><size>10</size></font>
  </theme>
  <desktops><number>1</number></desktops>
  <keyboard>
    <keybind key="A-F4"><action name="Close"/></keybind>
    <keybind key="A-Tab"><action name="NextWindow"/></keybind>
  </keyboard>
</openbox_config>
```

### Usage Example (TypeScript SDK)
```ts
const openboxConfig = `<?xml version="1.0" encoding="UTF-8"?>
<openbox_config xmlns="http://openbox.org/3.4/rc">
  <theme>
    <name>Clearlooks</name>
    <titleLayout>NLIMC</titleLayout>
    <font place="ActiveWindow"><name>DejaVu Sans</name><size>10</size></font>
  </theme>
  <desktops><number>1</number></desktops>
  <keyboard>
    <keybind key="A-F4"><action name="Close"/></keybind>
    <keybind key="A-Tab"><action name="NextWindow"/></keybind>
  </keyboard>
</openbox_config>`;

await sdk.mkdirFs({ path: "~/.local/state/sandbox-agent/desktop/home/.config/openbox" });
await sdk.writeFsFile(
  { path: "~/.local/state/sandbox-agent/desktop/home/.config/openbox/rc.xml" },
  openboxConfig,
);
```

### Usage Example (cURL)
```bash
curl -X POST "http://127.0.0.1:2468/v1/fs/mkdir?path=~/.local/state/sandbox-agent/desktop/home/.config/openbox"

curl -X PUT "http://127.0.0.1:2468/v1/fs/file?path=~/.local/state/sandbox-agent/desktop/home/.config/openbox/rc.xml" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @rc.xml
```

## Autostart Programs

### Description
Configure programs to automatically run when Openbox starts by creating or modifying the `autostart` script.

### File Path
`~/.config/openbox/autostart`

### Example Script
```bash
#!/bin/sh
# Set a solid background color
xsetroot -solid "#1e1e2e" &

# Launch a terminal
xterm -geometry 120x40+50+50 &
```

```

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

### Start and Stop Desktop

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/computer-use.mdx

Initiate or terminate the virtual desktop session. The start desktop command accepts optional parameters for resolution, DPI, and streaming/recording configurations.

```APIDOC
## POST /v1/desktop/start

### Description
Starts a virtual desktop session. All fields in the request are optional. Defaults are 1440x900 at 96 DPI.

### Method
POST

### Endpoint
/v1/desktop/start

### Parameters
#### Request Body
- **width** (number) - Optional - Desktop width in pixels. Defaults to 1440.
- **height** (number) - Optional - Desktop height in pixels. Defaults to 900.
- **dpi** (number) - Optional - Display DPI. Defaults to 96.
- **displayNum** (number) - Optional - Starting X display number. The runtime probes from this number upward to find an available display. Defaults to 99.
- **stateDir** (string) - Optional - Desktop state directory for home, logs, recordings. Defaults to (auto).
- **streamVideoCodec** (string) - Optional - WebRTC video codec (`vp8`, `vp9`, `h264`). Defaults to "vp8".
- **streamAudioCodec** (string) - Optional - WebRTC audio codec (`opus`, `g722`). Defaults to "opus".
- **streamFrameRate** (number) - Optional - Streaming frame rate (1-60). Defaults to 30.
- **webrtcPortRange** (string) - Optional - UDP port range for WebRTC media. Defaults to "59050-59070".
- **recordingFps** (number) - Optional - Default recording FPS when not specified in `startDesktopRecording` (1-60). Defaults to 30.

### Request Example
```json
{
  "width": 1920,
  "height": 1080,
  "streamVideoCodec": "h264",
  "streamFrameRate": 60,
  "webrtcPortRange": "59100-59120",
  "recordingFps": 15
}
```

## POST /v1/desktop/stop

### Description
Stops the virtual desktop session.

### Method
POST

### Endpoint
/v1/desktop/stop

### Response
#### Success Response (200)
- **state** (string) - The current state of the desktop (e.g., "inactive").
- **display** (string) - The display number being used (e.g., ":99").

### Response Example
```json
{
  "state": "inactive",
  "display": ":99"
}
```
```

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

### Install Rust with rustup

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs Rust using the official rustup installer script.

```TypeScript
await sdk.runProcess({
  command: "bash",
  args: ["-c", "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y"],
});
```

```cURL
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"bash","args":["-c","curl --proto =https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y"]}'
```

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

### Configure Autostart Programs for Openbox

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/computer-use.mdx

Set up autostart programs for Openbox by creating or modifying the autostart script. This example demonstrates setting a background color and launching a terminal.

```TypeScript
#!/bin/sh
# Set a solid background color
xsetroot -solid "#1e1e2e" &

# Launch a terminal
xterm -geometry 120x40+50+50 &

```

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

### Install Node.js with NVM

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/common-software.mdx

Installs Node Version Manager (nvm) and then installs Node.js version 22.

```TypeScript
await sdk.runProcess({
  command: "bash",
  args: ["-c", "curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && . ~/.nvm/nvm.sh && nvm install 22"],
});
```

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

### Install desktop runtime dependencies

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/cli.mdx

Installs Linux desktop runtime packages. Use --yes to skip confirmation or --print-only to see the command without execution. Requires sudo if not run as root.

```bash
sandbox-agent install desktop [OPTIONS]
```

```bash
sandbox-agent install desktop --yes
```

```bash
sandbox-agent install desktop --print-only
```

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

### API Agents Install

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/cli.mdx

Installs a specified agent. Supports reinstalling an agent if it's already installed.

```APIDOC
## api agents install

### Description
Installs a specified agent.

### Method
CLI Command

### Endpoint
sandbox-agent api agents install <AGENT> [--reinstall] [--endpoint <URL>]

### Parameters
#### Path Parameters
- **AGENT** (string) - Required - The name of the agent to install.

#### Query Parameters
- **--reinstall** (boolean) - Optional - Reinstall the agent if already installed.
- **--endpoint** (string) - Optional - Target server URL (default: `http://127.0.0.1:2468`)

### Request Example
```bash
sandbox-agent api agents install codex --reinstall
```
```

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

### Start Sandbox Agent SDK

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/docs/quickstart.mdx

Initialize the Sandbox Agent SDK. This is the first step to interact with the agent.

```typescript
import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.start();
```

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

### Run the Sandbox Agent Locally

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/CONTRIBUTING.md

Starts the sandbox agent with specified token and host/port. Ensure you have a SANDBOX_TOKEN configured.

```bash
sandbox-agent --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```

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

### Install Gigacode with npm

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/gigacode/README.md

Install Gigacode globally using npm. After installation, you can run `gigacode --help` to see available commands.

```bash
npm install -g @sandbox-agent/gigacode
gigacode --help
```

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

### Install Gigacode with cURL (macOS/Linux/WSL)

Source: https://github.com/rivet-dev/sandbox-agent/blob/main/gigacode/README.md

Use this command to download and execute the installation script for Gigacode on macOS, Linux, or WSL. This is the recommended installation method for these platforms.

```bash
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/gigacode-install.sh | sh
```