Sandbox Agent

https://rivet.dev/sandbox-agent/docs/
Admin
Sandbox Agent is an HTTP server that runs inside sandboxes to provide a unified API and SDK for...
Tokens:112,585
Snippets:1,117
Trust Score:8.4
Update:6 days ago
Show doc for...
Tokens:
Raw
### sandbox-agent daemon start examples

Source: https://rivet.dev/sandbox-agent/docs/cli

Examples of starting the daemon: with default settings and with the --upgrade flag.

```bash
sandbox-agent daemon start
sandbox-agent daemon start --upgrade
```

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

### Install and Start PostgreSQL with SDK

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs PostgreSQL and PostgreSQL client, then starts the PostgreSQL 15 service using the SDK's runProcess and createProcess methods.

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

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

### Install and Start Redis with SDK

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs Redis server and starts it in daemon mode using the SDK's runProcess and createProcess methods.

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

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

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

### sandbox-agent install-agent examples

Source: https://rivet.dev/sandbox-agent/docs/cli

Two example invocations: reinstalling the claude agent and installing all supported agents. The --all flag installs every supported agent.

```bash
sandbox-agent install-agent claude --reinstall
```

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

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

### Install sandbox-agent and @daytonaio/sdk

Source: https://rivet.dev/sandbox-agent/docs/deploy/daytona

Install the required npm packages for the TypeScript example.

```bash
npm install sandbox-agent@0.5.x @daytonaio/sdk
```

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

### Install packages and start Modal sandbox

Source: https://rivet.dev/sandbox-agent/docs/deploy/modal

Install the modal provider and sandbox-agent package, then start a sandbox with the modal provider. The provider handles app creation, image building, provisioning, agent installation, server startup, and tunnel networking. Environment variables are passed as Modal Secrets.

```bash
npm install sandbox-agent@0.5.x modal
```

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

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

### TypeScript Example: Start Vercel Sandbox and Create Session

Source: https://rivet.dev/sandbox-agent/docs/deploy/vercel

This example imports SandboxAgent and the vercel provider, sets environment variables for Anthropic or OpenAI API keys, starts a sandbox with Node 24 runtime, creates a session with the 'claude' agent, prompts it to summarize the repository, and destroys the sandbox in a finally block. The vercel provider handles sandbox creation, agent installation, setup, and server startup automatically.

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

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

const sdk = await SandboxAgent.start({
  sandbox: vercel({
    create: {
      runtime: "node24",
      env,
    },
  }),
});

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

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

### Install and Start Redis with cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs Redis server and starts it in daemon mode using cURL commands to the Rivet API.

```bash
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 Node.js and npm using TypeScript SDK

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses sdk.runProcess to run apt-get to install nodejs and npm. This is the initial setup for Node.js in the sandbox.

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

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

### Install dependencies for E2B TypeScript example

Source: https://rivet.dev/sandbox-agent/docs/deploy/e2b

Install the sandbox-agent and @e2b/code-interpreter packages using npm.

```bash
npm install sandbox-agent@0.5.x @e2b/code-interpreter
```

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

### Install VLC (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs VLC desktop application. Requires the Computer Use desktop to be started first.

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

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

### Install and run VS Code (code-server) (cURL)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs code-server via the install script, then creates a process to run it on port 8080 with authentication disabled. Requires the Computer Use desktop to be started first.

```bash
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"]}'
```

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

### Install desktop with --yes and --print-only

Source: https://rivet.dev/sandbox-agent/docs/cli

Two example invocations of the install desktop command: one that skips the confirmation prompt with --yes, and one that prints the package-manager command without executing it with --print-only.

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

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

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

### Install build-essential, cmake, pkg-config (cURL)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs the standard build toolchain via the Rivet API. Equivalent to the TypeScript example.

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

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

### Install LibreOffice (cURL)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs LibreOffice via the Rivet API. Requires the Computer Use desktop to be started first.

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

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

### Install VLC (cURL)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs VLC via the Rivet API. Requires the Computer Use desktop to be started first.

```bash
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"]}'
```

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

### Install GIMP (cURL)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs GIMP via the Rivet API. Requires the Computer Use desktop to be started first.

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

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

### Install Git using cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Sends a POST request to the local Rivet API endpoint to run the apt-get install command for Git. This is the cURL version of the example.

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

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

### Install Git using Rivet SDK (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses the Rivet SDK's runProcess method to install Git via apt-get. This is the TypeScript version of the example.

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

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

### Install and run VS Code (code-server) (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs code-server via the install script, then creates a process to run it on port 8080 with authentication disabled. Requires the Computer Use desktop to be started first.

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

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

### Install GIMP (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs GIMP desktop application. Requires the Computer Use desktop to be started first.

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

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

### Run server with bun global install

Source: https://rivet.dev/sandbox-agent/docs/quickstart

Install globally via bun, trust the postinstall scripts, and run the server.

```bash
bun add -g @sandbox-agent/cli@0.5.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
```

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

### Install LibreOffice (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs LibreOffice desktop application. Requires the Computer Use desktop to be started first.

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

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

### Start server with authentication and attach with password

Source: https://rivet.dev/sandbox-agent/docs/opencode-compatibility

Starts the server with token authentication and attaches the OpenCode CLI using the same token as password.

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

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

### Dockerfile for pre-installing software

Source: https://rivet.dev/sandbox-agent/docs/common-software

Use this Dockerfile to pre-install common tools and Python packages in a Docker image for production. This avoids repeated downloads and speeds up startup. The example installs Chromium, Firefox, Node.js, Python, and other utilities, then installs numpy, pandas, and matplotlib via pip.

```dockerfile
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    chromium \
    firefox-esr \
    nodejs npm \
    python3 python3-pip \
    git curl wget \
    build-essential \
    sqlite3 \
    ffmpeg \
    imagemagick \
    jq \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install numpy pandas matplotlib
```

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

### Run server with npm global install

Source: https://rivet.dev/sandbox-agent/docs/quickstart

Install globally via npm and run the server.

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

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

### Run full image with desktop API support

Source: https://rivet.dev/sandbox-agent/docs/deploy/docker

Installs desktop dependencies inside the container before starting the server. Uses node:22-bookworm-slim as the base image and runs the install script from releases.rivet.dev.

```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.5.x/install.sh | sh && \
    sandbox-agent install desktop --yes && \
    sandbox-agent server --no-token --host 0.0.0.0 --port 3000"
```

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

### Install Chromium via cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses the Process API to install Chromium and chromium-sandbox via apt-get. This is the cURL equivalent of the TypeScript example.

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

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

### Start and stop desktop with TypeScript SDK

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Connects to the Sandbox Agent and starts a desktop session with specified dimensions, then stops it. The start request returns a status with state 'active' and display ':99'. All start fields are optional; defaults are 1440x900 at 96 DPI.

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

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

### Install Ruby using TypeScript SDK

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses sdk.runProcess to run apt-get to install ruby-full.

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

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

### Start server and attach manually with OpenCode CLI

Source: https://rivet.dev/sandbox-agent/docs/opencode-compatibility

Starts the server without token and attaches the OpenCode CLI to the local endpoint.

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

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

### Install Docker using Rivet SDK (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses the Rivet SDK's runProcess method to install Docker by running a shell command that downloads and executes the Docker installation script.

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

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

### Install SQLite with SDK

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs SQLite3 using the SDK's runProcess method.

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

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

### Install Java (OpenJDK) using cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Sends a POST request to run apt-get to install default-jdk.

```bash
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 Ruby using cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Sends a POST request to run apt-get to install ruby-full.

```bash
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 MariaDB with SDK

Source: https://rivet.dev/sandbox-agent/docs/common-software

Installs MariaDB server and client using the SDK's runProcess method.

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

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

### Install and run Sandbox Agent CLI

Source: https://rivet.dev/sandbox-agent/docs/deploy/local

Install the CLI via curl and run the server with no token on 127.0.0.1:2468.

```bash
# Install
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.5.x/install.sh | sh

# Run
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
```

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

### Install @sandbox-agent/react

Source: https://rivet.dev/sandbox-agent/docs/react-components

Install the React components package with npm. Use version 0.5.x as shown.

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

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

### POST /v1/desktop/recording/start

Source: https://rivet.dev/sandbox-agent/docs/api-reference/tags/v1

Starts desktop recording.

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

### Description
Starts desktop recording.

### Method
POST

### Endpoint
/v1/desktop/recording/start

```

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

### startDesktopRecording

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Starts recording the desktop screen. Returns a DesktopRecordingInfo.

```APIDOC
## startDesktopRecording

### Description
Starts recording the desktop screen.

### Method
startDesktopRecording

### Parameters
- **request** (optional) - Optional request parameters for the recording.

### Returns
- **DesktopRecordingInfo** - Information about the recording.
```

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

### Install Node.js and npm using cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Sends a POST request to the sandbox API to run apt-get to install nodejs and npm.

```bash
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"]}'
```

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

### POST /v1/desktop/start

Source: https://rivet.dev/sandbox-agent/docs/api-reference/tags/v1

Start the private desktop runtime.

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

### Description
Start the private desktop runtime.

### Method
POST

### Endpoint
/v1/desktop/start

```

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

### POST /v1/desktop/recording/start

Source: https://rivet.dev/sandbox-agent/docs/api-reference/operations/post_v1_desktop_recording_start

Starts an ffmpeg x11grab recording against the managed desktop and returns the created recording metadata.

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

### Description
Starts an ffmpeg x11grab recording against the managed desktop and returns the created recording metadata.

### Method
POST

### Endpoint
/v1/desktop/recording/start

### Parameters
#### Request Body
Required. Content type: application/json. Schema: DesktopRecordingStartRequest. See [DesktopRecordingStartRequest](/sandbox-agent/docs/api-reference/schemas/desktoprecordingstartrequest/).

### Response
#### Success Response (200)
Desktop recording started. Content type: application/json. Schema: DesktopRecordingInfo. See [DesktopRecordingInfo](/sandbox-agent/docs/api-reference/schemas/desktoprecordinginfo/).

#### Error Response (409)
Desktop runtime is not ready or a recording is already active. Content type: application/json. Schema: ProblemDetails. See [ProblemDetails](/sandbox-agent/docs/api-reference/schemas/problemdetails/).

#### Error Response (502)
Desktop recording failed. Content type: application/json. Schema: ProblemDetails. See [ProblemDetails](/sandbox-agent/docs/api-reference/schemas/problemdetails/).
```

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

### POST /v1/desktop/start

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Starts a virtual desktop session with optional configuration for resolution, streaming, and recording. Returns the desktop status including the display number.

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

### Description
Starts a virtual desktop session with optional configuration for resolution, streaming, and recording. Returns the desktop status including the display number.

### Method
POST

### Endpoint
/v1/desktop/start

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

### Request Example
{
  "width": 1920,
  "height": 1080,
  "dpi": 96
}

### Response
#### Success Response (200)
- **state** (string) - The state of the desktop session, e.g., "active"
- **display** (string) - The display number, e.g., ":99"

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

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

### sandbox-agent api agents install codex --reinstall

Source: https://rivet.dev/sandbox-agent/docs/cli

Installs an agent, using the `--reinstall` flag to force reinstallation. The example installs the `codex` agent.

```bash
sandbox-agent api agents install codex --reinstall
```

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

### startDesktop

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Starts the desktop session. Returns a DesktopStatusResponse indicating the status of the desktop.

```APIDOC
## startDesktop

### Description
Starts the desktop session.

### Method
startDesktop

### Parameters
- **request** (optional) - Optional request parameters.

### Returns
- **DesktopStatusResponse** - The status of the desktop.
```

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

### Run server with Bun local SDK

Source: https://rivet.dev/sandbox-agent/docs/quickstart

Install the package, trust postinstall scripts, and use SandboxAgent.start() to manage the server as a subprocess.

```bash
bun add sandbox-agent@0.5.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
```

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

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

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

### Quick start: create Cloudflare sandbox project

Source: https://rivet.dev/sandbox-agent/docs/deploy/cloudflare

Creates a new Cloudflare sandbox project using the minimal template and enters the project directory.

```bash
npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal
cd my-sandbox
```

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

### Install Firefox via cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses the Process API to install Firefox ESR via apt-get. This is the cURL equivalent of the TypeScript example.

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

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

### POST /v1/desktop/start

Source: https://rivet.dev/sandbox-agent/docs/api-reference/operations/post_v1_desktop_start

Lazily launches the managed Xvfb/openbox stack, validates display health, and returns the resulting desktop status snapshot.

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

### Description
Lazily launches the managed Xvfb/openbox stack, validates display health, and returns the resulting desktop status snapshot.

### Method
POST

### Endpoint
/v1/desktop/start

### Parameters
#### Request Body
Required. The request body must be in application/json format and conform to the DesktopStartRequest schema.

### Request Example
```json
{
  "schema": {
    "$ref": "#/components/schemas/DesktopStartRequest"
  }
}
```

### Response
#### Success Response (200)
Desktop runtime status after start. Content type: application/json. Response body conforms to the DesktopStatusResponse schema.

#### Response Example
```json
{
  "schema": {
    "$ref": "#/components/schemas/DesktopStatusResponse"
  }
}
```

#### Error Responses
- **400** - Invalid desktop start request. Content type: application/json. Response body conforms to the ProblemDetails schema.
- **409** - Desktop runtime is already transitioning. Content type: application/json. Response body conforms to the ProblemDetails schema.
- **501** - Desktop API unsupported on this platform. Content type: application/json. Response body conforms to the ProblemDetails schema.
- **503** - Desktop runtime could not be started. Content type: application/json. Response body conforms to the ProblemDetails schema.

```

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

### sandbox-agent daemon start [OPTIONS]

Source: https://rivet.dev/sandbox-agent/docs/cli

Starts the background daemon. Options include -H/--host (default 127.0.0.1), -p/--port (default 2468), and --upgrade to use ensure-running + upgrade behavior.

```bash
sandbox-agent daemon start [OPTIONS]
```

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

### Install Playwright Browsers via cURL

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses the Process API to run npx playwright install with dependencies. This is the cURL equivalent of the TypeScript example.

```bash
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
  -H "Content-Type: application/json" \
  -d '{"command":"npx","args":["playwright","install","--with-deps","chromium"]}'
```

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

### POST /v1/desktop/stream/start

Source: https://rivet.dev/sandbox-agent/docs/api-reference/tags/v1

Start desktop streaming.

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

### Description
Start desktop streaming.

### Method
POST

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

```

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

### Create snapshot for faster startup

Source: https://rivet.dev/sandbox-agent/docs/deploy/daytona

Checks for an existing snapshot named 'sandbox-agent-ready' and creates it if missing, using a base Ubuntu image with commands to install the sandbox agent and its agents. This snapshot can be used to speed up subsequent sandbox startups.

```typescript
import { Daytona, Image } from "@daytonaio/sdk";

const daytona = new Daytona();
const SNAPSHOT = "sandbox-agent-ready";

const hasSnapshot = await daytona.snapshot.get(SNAPSHOT).then(() => true, () => false);

if (!hasSnapshot) {
  await daytona.snapshot.create({
    name: SNAPSHOT,
    image: Image.base("ubuntu:22.04").runCommands(
      "apt-get update && apt-get install -y curl ca-certificates",
      "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.5.x/install.sh | sh",
      "sandbox-agent install-agent claude",
      "sandbox-agent install-agent codex",
    ),
  });
}
```

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

### TypeScript example using SandboxAgent with computesdk

Source: https://rivet.dev/sandbox-agent/docs/deploy/computesdk

Starts a sandbox using the computesdk provider, creates a session, prompts the agent, and destroys the sandbox. The computesdk provider handles sandbox creation, agent installation, and server startup. The create option forwards the full ComputeSDK sandbox-create payload, including provider-specific fields like image and templateId.

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

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 sdk = await SandboxAgent.start({
  sandbox: computesdk({
    create: {
      envs,
      image: process.env.COMPUTESDK_IMAGE,
      templateId: process.env.COMPUTESDK_TEMPLATE_ID,
    },
  }),
});

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

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

### Install Go and add to PATH (TypeScript SDK)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Two sdk.runProcess calls: first downloads and extracts Go 1.23.6; second exports PATH and verifies go version.

```TypeScript
await sdk.runProcess({
  command: "bash",
  args: ["-c", "curl -fsSL https://go.dev/dl/go1.23.6.linux-amd64.tar.gz | tar -C /usr/local -xz"],
});

// Add to PATH for subsequent commands
await sdk.runProcess({
  command: "bash",
  args: ["-c", "export PATH=$PATH:/usr/local/go/bin && go version"],
});
```

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

### Start desktop with streaming and recording options (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Starts a desktop session with custom streaming and recording defaults: h264 video codec, 60 FPS, a specific WebRTC port range, and 15 FPS recording. These options configure defaults for the session and take effect when streaming or recording is started later.

```TypeScript
const status = await sdk.startDesktop({
  width: 1920,
  height: 1080,
  streamVideoCodec: "h264",
  streamFrameRate: 60,
  webrtcPortRange: "59100-59120",
  recordingFps: 15,
});
```

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

### OpenCode SDK client example

Source: https://rivet.dev/sandbox-agent/docs/opencode-compatibility

Creates an OpenCode client, creates a session, sends a prompt, and subscribes to events.

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

const client = createOpencodeClient({
  baseUrl: "http://localhost:2468/opencode",
});

const session = await client.session.create();

await client.session.promptAsync({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Hello, write a hello world script" }],
  },
});

const events = await client.event.subscribe({});
for await (const event of events.stream) {
  console.log(event);
}
```

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

### Set up SQLiteSessionPersistDriver with install command and connection

Source: https://rivet.dev/sandbox-agent/docs/session-persistence

Set up durable SQLite persistence for local or server Node apps. Install better-sqlite3, then import a SQLiteSessionPersistDriver (from ./persist.ts) configured with a filename, and pass it to SandboxAgent.connect. For the full driver implementation, see the linked persist-sqlite example.

```bash
npm install better-sqlite3
```

```ts
import { SandboxAgent } from "sandbox-agent";
import { SQLiteSessionPersistDriver } from "./persist.ts";

const persist = new SQLiteSessionPersistDriver({
  filename: "./sandbox-agent.db",
});

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

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

### Get and set process config (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/processes

Retrieves the current process configuration and updates it with new limits. The example sets maxConcurrentProcesses to 32 and defaultRunTimeoutMs to 60000.

```TypeScript
const config = await sdk.getProcessConfig();
console.log(config);

await sdk.setProcessConfig({
  ...config,
  maxConcurrentProcesses: 32,
  defaultRunTimeoutMs: 60000,
});
```

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

### Set up PostgresSessionPersistDriver with install command and connection

Source: https://rivet.dev/sandbox-agent/docs/session-persistence

Use Postgres for shared relational storage when you already run a Postgres server. Install the pg packageholed, then configure PostgresSessionPersistDriver with a connection string from process.env.DATABASE_URL and a schema, and pass it to SandboxAgent.connect. The full driver implementation is available in the linked persist-postgres example.

```bash
npm install pg
```

```ts
import { SandboxAgent } from "sandbox-agent";
import { PostgresSessionPersistDriver } from "./persist.ts";

const persist = new PostgresSessionPersistDriver({
  connectionString: process.env.DATABASE_URL,
  schema: "public",
});

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

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

### Pass LLM credentials via spawn.env

Source: https://rivet.dev/sandbox-agent/docs/llm-credentials

Use this TypeScript example to start a SandboxAgent with Anthropic and OpenAI API keys. Each call to SandboxAgent.start() can use different credentials.

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

const sdk = await SandboxAgent.start({
  spawn: {
    env: {
      ANTHROPIC_API_KEY: "sk-ant-...",
      OPENAI_API_KEY: "sk-...",
    },
  },
});
```

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

### Create a Pi agent session

Source: https://rivet.dev/sandbox-agent/docs/agents/pi

Use the client's createSession method with the agent set to 'pi' to start a session with the Pi agent. This is the only usage example provided.

```typescript
const session = await client.createSession({
  agent: "pi",
});
```

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

### sandbox-agent install-agent usage

Source: https://rivet.dev/sandbox-agent/docs/cli

Shows the command syntax for installing or reinstalling an agent. Use --all to install every supported agent, -r/--reinstall to force reinstall, and --agent-version or --agent-process-version to override versions (these conflict with --all).

```bash
sandbox-agent install-agent [<AGENT>] [OPTIONS]
```

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

### TypeScript example with cloudflare provider

Source: https://rivet.dev/sandbox-agent/docs/deploy/cloudflare

Starts a sandbox using the cloudflare provider, creates a session with agent codex, prompts it, and destroys the sandbox. The provider uses containerFetch and strips AbortSignal.

```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 server with curl

Source: https://rivet.dev/sandbox-agent/docs/quickstart

Install and run the binary directly using curl.

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

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

### Set background with feh (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Uploads a wallpaper image and writes an autostart script that uses feh to set it as the background. Requires feh to be installed (not by default) via the Process API before starting the desktop.

```TypeScript
// Upload a wallpaper image
import fs from "node:fs";

const wallpaper = await fs.promises.readFile("./wallpaper.png");
await sdk.writeFsFile(
  { path: "~/.local/state/sandbox-agent/desktop/home/wallpaper.png" },
  wallpaper,
);

// Set the autostart to apply it
const autostart = `#!/bin/sh
feh --bg-fill ~/wallpaper.png &
`;

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

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

### TypeScript example with Durable Objects

Source: https://rivet.dev/sandbox-agent/docs/deploy/cloudflare

Shows how to use SandboxAgent.connect with a custom fetch backed by sandbox.containerFetch for Workers with Durable Objects. Includes helper functions to check server status and start the sandbox-agent server.

```typescript
import { getSandbox, type Sandbox } from "@cloudflare/sandbox";
import { Hono } from "hono";
import { SandboxAgent } from "sandbox-agent";

export { Sandbox } from "@cloudflare/sandbox";

type Bindings = {
  Sandbox: DurableObjectNamespace<Sandbox>;
  ASSETS: Fetcher;
  ANTHROPIC_API_KEY?: string;
  OPENAI_API_KEY?: string;
};

const app = new Hono<{ Bindings: Bindings }>();
const PORT = 8000;

async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
  try {
    const result = await sandbox.exec(`curl -sf http://localhost:${PORT}/v1/health`);
    return result.success;
  } catch {
    return false;
  }
}

async function getReadySandbox(name: string, env: Bindings): Promise<Sandbox> {
  const sandbox = getSandbox(env.Sandbox, name);
  if (!(await isServerRunning(sandbox))) {
    const envVars: Record<string, string> = {};
    if (env.ANTHROPIC_API_KEY) envVars.ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY;
    if (env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = env.OPENAI_API_KEY;
    await sandbox.setEnvVars(envVars);
    await sandbox.startProcess(`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`);
  }
  return sandbox;
}

app.post("/sandbox/:name/prompt", async (c) => {
  const sandbox = await getReadySandbox(c.req.param("name"), c.env);

  const sdk = await SandboxAgent.connect({
    fetch: (input, init) =>
      sandbox.containerFetch(
        input as Request | string | URL,
        {
          ...(init ?? {}),
          // Avoid passing AbortSignal through containerFetch; it can drop streamed session updates.
          signal: undefined,
        },
        PORT,
      ),
  });

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

  return c.json(response);
});

app.all("/sandbox/:name/proxy/*", async (c) => {
  const sandbox = await getReadySandbox(c.req.param("name"), c.env);
  const wildcard = c.req.param("*");
  const path = wildcard ? `/${wildcard}` : "/";
  const query = new URL(c.req.raw.url).search;

  return sandbox.containerFetch(new Request(`http://localhost${path}${query}`, c.req.raw), PORT);
});

app.all("*", (c) => c.env.ASSETS.fetch(c.req.raw));

export default app;
```

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

### Pass user-provided API key via spawn.env

Source: https://rivet.dev/sandbox-agent/docs/llm-credentials

TypeScript example that starts a Sandbox Agent with a user-provided Anthropic API key passed through spawn.env. The key is visible to the agent and anything inside the sandbox.

```typescript
const sdk = await SandboxAgent.start({
  spawn: {
    env: {
      ANTHROPIC_API_KEY: userProvidedKey,
    },
  },
});
```

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

### TypeScript example using daytona provider

Source: https://rivet.dev/sandbox-agent/docs/deploy/daytona

Starts a sandbox with the daytona provider, creates a session with the 'claude' agent, prompts it to summarize the repository, and destroys the sandbox in a finally block. Requires DAYTONA_API_KEY and either ANTHROPIC_API_KEY or OPENAI_API_KEY.

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

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

### Create tenant sandbox with scoped key via OpenRouter

Source: https://rivet.dev/sandbox-agent/docs/llm-credentials

TypeScript example that issues a scoped key for a tenant via OpenRouter's Provisioning API and starts a Sandbox Agent with that key as OPENAI_API_KEY. The key has a monthly limit of 50 credits.

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

async function createTenantSandbox(tenantId: string) {
  // Issue a scoped key for this tenant via OpenRouter
  const res = await fetch("https://openrouter.ai/api/v1/keys", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_PROVISIONING_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: `tenant-${tenantId}`,
      limit: 50,
      limitResetType: "monthly",
    }),
  });
  const { key } = await res.json();

  // Start a sandbox with the tenant's scoped key
  const sdk = await SandboxAgent.start({
    spawn: {
      env: {
        OPENAI_API_KEY: key, // OpenRouter uses OpenAI-compatible endpoints
      },
    },
  });

  const session = await sdk.createSession({
    agent: "claude",
    sessionInit: { cwd: "/workspace" },
  });

  return { sdk, session };
}
```

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

### TypeScript example using e2b provider

Source: https://rivet.dev/sandbox-agent/docs/deploy/e2b

Starts a sandbox with the e2b provider, creates a session with the 'claude' agent, prompts it to summarize the repository, and logs the stop reason. The sandbox is destroyed in a finally block. Requires E2B_API_KEY and either ANTHROPIC_API_KEY or OPENAI_API_KEY.

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

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

### Desktop API usage

Source: https://rivet.dev/sandbox-agent/docs/sdk-overview

Demonstrates querying desktop status, starting the desktop runtime, taking screenshots, and performing mouse, keyboard, and text input actions. The screenshot helper returns Uint8Array PNG bytes. The SDK does not install OS packages remotely; callers should surface missingDependencies and installCommand from getDesktopStatus().

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

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

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

const screenshot = await sdk.takeDesktopScreenshot();
const displayInfo = await sdk.getDesktopDisplayInfo();

await sdk.moveDesktopMouse({ x: 400, y: 300 });
await sdk.clickDesktop({ x: 400, y: 300, button: "left", clickCount: 1 });
await sdk.typeDesktopText({ text: "hello world", delayMs: 10 });
await sdk.pressDesktopKey({ key: "ctrl+l" });

await sdk.stopDesktop();
```

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

### sandbox-agent opencode example

Source: https://rivet.dev/sandbox-agent/docs/cli

Runs the opencode command with default options.

```bash
sandbox-agent opencode
```

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

### Get focused window with cURL

Source: https://rivet.dev/sandbox-agent/docs/computer-use

Use GET request to the /v1/desktop/windows/focused endpoint to get the focused window. Returns 404 if no window has focus.

```cURL
curl "http://127.0.0.1:2468/v1/desktop/windows/focused"
```

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

### GET /v1/fs/stat

Source: https://rivet.dev/sandbox-agent/docs/api-reference

Gets filesystem entry statistics.

```APIDOC
## GET /v1/fs/stat

### Description
Gets filesystem entry statistics.

### Method
GET

### Endpoint
/v1/fs/stat
```

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

### Install jq using Rivet SDK (TypeScript)

Source: https://rivet.dev/sandbox-agent/docs/common-software

Uses the Rivet SDK's runProcess method to install jq via apt-get.

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