mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 08:03:46 +00:00
docs: documentation overhaul and universal schema reference (#10)
* remove website .astro * fix default origin * docs: comprehensive documentation overhaul - Add quickstart with multi-platform examples (E2B, Daytona, Docker, local) - Add environment variables setup with platform-specific tabs - Add Python SDK page (coming soon) - Add local deployment guide - Update E2B/Daytona/Docker guides with TypeScript examples - Configure OpenAPI auto-generation for API reference - Add CORS configuration guide - Update manage-sessions with Rivet Actors examples - Fix SDK method names and URLs throughout - Add icons to main documentation pages - Remove outdated universal-api and http-api pages * docs: add universal schema and agent compatibility docs - Create universal-schema.mdx with full event/item schema reference - Create agent-compatibility.mdx mirroring README feature matrix - Rename glossary.md to universal-schema.mdx - Update CLAUDE.md with sync requirements for new docs - Add links in README to building-chat-ui, manage-sessions, universal-schema - Fix CLI docs link (rivet.dev -> sandboxagent.dev) * docs: add inspector page and daytona network limits warning
This commit is contained in:
Nathan Flurry
GitHub
parent
a6f77f3008
commit
08d299a3ef
40 changed files with 1996 additions and 1004 deletions
|
|
@ -1,21 +1,90 @@
|
|||
---
|
||||
title: "Daytona"
|
||||
description: "Run the daemon in a Daytona workspace."
|
||||
description: "Run the daemon in a Daytona workspace."
|
||||
---
|
||||
|
||||
## Steps
|
||||
<Note>
|
||||
Daytona has [network egress limits](https://www.daytona.io/docs/en/network-limits/) on lower tiers. OpenAI and Anthropic APIs are whitelisted on all tiers, but other external services may be restricted on Tier 1 & 2.
|
||||
</Note>
|
||||
|
||||
1. Create a Daytona workspace with Rust and curl available.
|
||||
2. Install or build the sandbox-agent binary.
|
||||
3. Start the daemon and expose port `2468` (or your preferred port).
|
||||
## Prerequisites
|
||||
|
||||
```bash
|
||||
export SANDBOX_TOKEN="..."
|
||||
- `DAYTONA_API_KEY` environment variable
|
||||
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
|
||||
|
||||
cargo run -p sandbox-agent -- server \
|
||||
--token "$SANDBOX_TOKEN" \
|
||||
--host 0.0.0.0 \
|
||||
--port 2468
|
||||
## TypeScript Example
|
||||
|
||||
```typescript
|
||||
import { Daytona, Image } from "@daytonaio/sdk";
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
|
||||
const daytona = new Daytona();
|
||||
|
||||
// Pass API keys to the sandbox
|
||||
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 sandbox = await daytona.create({ envVars });
|
||||
|
||||
// Install sandbox-agent
|
||||
await sandbox.process.executeCommand(
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"
|
||||
);
|
||||
|
||||
// Start the server in the background
|
||||
await sandbox.process.executeCommand(
|
||||
"nohup sandbox-agent server --no-token --host 0.0.0.0 --port 3000 >/tmp/sandbox-agent.log 2>&1 &"
|
||||
);
|
||||
|
||||
// Wait for server to be ready
|
||||
await new Promise((r) => setTimeout(r, 2000));
|
||||
|
||||
// Get the public URL
|
||||
const baseUrl = (await sandbox.getSignedPreviewUrl(3000, 4 * 60 * 60)).url;
|
||||
|
||||
// Connect and use the SDK
|
||||
const client = await SandboxAgent.connect({ baseUrl });
|
||||
|
||||
await client.createSession("my-session", {
|
||||
agent: "claude",
|
||||
permissionMode: "default",
|
||||
});
|
||||
|
||||
// Cleanup when done
|
||||
await sandbox.delete();
|
||||
```
|
||||
|
||||
4. Use your Daytona port forwarding to reach the daemon from your client.
|
||||
## Using Snapshots for Faster Startup
|
||||
|
||||
For production, use snapshots with pre-installed binaries:
|
||||
|
||||
```typescript
|
||||
import { Daytona, Image } from "@daytonaio/sdk";
|
||||
|
||||
const daytona = new Daytona();
|
||||
const SNAPSHOT = "sandbox-agent-ready";
|
||||
|
||||
// Create snapshot once (takes 2-3 minutes)
|
||||
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/latest/install.sh | sh",
|
||||
"sandbox-agent install-agent claude",
|
||||
"sandbox-agent install-agent codex",
|
||||
),
|
||||
});
|
||||
}
|
||||
|
||||
// Now sandboxes start instantly
|
||||
const sandbox = await daytona.create({
|
||||
snapshot: SNAPSHOT,
|
||||
envVars,
|
||||
});
|
||||
```
|
||||
|
||||
See [Daytona Snapshots](https://daytona.io/docs/snapshots) for details.
|
||||
|
|
|
|||
|
|
@ -1,27 +1,75 @@
|
|||
---
|
||||
title: "Docker (dev)"
|
||||
title: "Docker"
|
||||
description: "Build and run the daemon in a Docker container."
|
||||
---
|
||||
|
||||
## Build the binary
|
||||
<Warning>
|
||||
Docker is not recommended for production. Standard Docker containers don't provide sufficient isolation for running untrusted code. Use a dedicated sandbox provider like E2B or Daytona for production workloads.
|
||||
</Warning>
|
||||
|
||||
Use the release Dockerfile to build a static binary:
|
||||
## Quick Start
|
||||
|
||||
Run sandbox-agent in a container with agents pre-installed:
|
||||
|
||||
```bash
|
||||
docker run --rm -p 3000:3000 \
|
||||
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
|
||||
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
|
||||
debian:bookworm-slim bash -lc "\
|
||||
apt-get update && apt-get install -y curl ca-certificates && \
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh && \
|
||||
sandbox-agent install-agent claude && \
|
||||
sandbox-agent install-agent codex && \
|
||||
sandbox-agent server --no-token --host 0.0.0.0 --port 3000"
|
||||
```
|
||||
|
||||
Access the API at `http://localhost:3000`.
|
||||
|
||||
## TypeScript with dockerode
|
||||
|
||||
```typescript
|
||||
import Docker from "dockerode";
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
|
||||
const docker = new Docker();
|
||||
const PORT = 3000;
|
||||
|
||||
const container = await docker.createContainer({
|
||||
Image: "debian:bookworm-slim",
|
||||
Cmd: ["bash", "-lc", [
|
||||
"apt-get update && apt-get install -y curl ca-certificates",
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh",
|
||||
"sandbox-agent install-agent claude",
|
||||
"sandbox-agent install-agent codex",
|
||||
`sandbox-agent server --no-token --host 0.0.0.0 --port ${PORT}`,
|
||||
].join(" && ")],
|
||||
ExposedPorts: { [`${PORT}/tcp`]: {} },
|
||||
HostConfig: {
|
||||
AutoRemove: true,
|
||||
PortBindings: { [`${PORT}/tcp`]: [{ HostPort: `${PORT}` }] },
|
||||
},
|
||||
});
|
||||
|
||||
await container.start();
|
||||
|
||||
// Wait for server and connect
|
||||
const baseUrl = `http://127.0.0.1:${PORT}`;
|
||||
const client = await SandboxAgent.connect({ baseUrl });
|
||||
|
||||
// Use the client...
|
||||
await client.createSession("my-session", {
|
||||
agent: "claude",
|
||||
permissionMode: "default",
|
||||
});
|
||||
```
|
||||
|
||||
## Building from Source
|
||||
|
||||
To build a static binary for use in minimal containers:
|
||||
|
||||
```bash
|
||||
docker build -f docker/release/linux-x86_64.Dockerfile -t sandbox-agent-build .
|
||||
|
||||
docker run --rm -v "$PWD/artifacts:/artifacts" sandbox-agent-build
|
||||
```
|
||||
|
||||
The binary will be written to `./artifacts/sandbox-agent-x86_64-unknown-linux-musl`.
|
||||
|
||||
## Run the daemon
|
||||
|
||||
```bash
|
||||
docker run --rm -p 2468:2468 \
|
||||
-v "$PWD/artifacts:/artifacts" \
|
||||
debian:bookworm-slim \
|
||||
/artifacts/sandbox-agent-x86_64-unknown-linux-musl server --token "$SANDBOX_TOKEN" --host 0.0.0.0 --port 2468
|
||||
```
|
||||
|
||||
You can now access the API at `http://localhost:2468`.
|
||||
The binary will be at `./artifacts/sandbox-agent-x86_64-unknown-linux-musl`.
|
||||
|
|
|
|||
|
|
@ -3,23 +3,77 @@ title: "E2B"
|
|||
description: "Deploy the daemon inside an E2B sandbox."
|
||||
---
|
||||
|
||||
## Steps
|
||||
## Prerequisites
|
||||
|
||||
1. Start an E2B sandbox with network access.
|
||||
2. Install the agent binaries you need (Claude, Codex, OpenCode, Amp).
|
||||
3. Run the daemon and expose its port.
|
||||
- `E2B_API_KEY` environment variable
|
||||
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` for the coding agents
|
||||
|
||||
Example startup script:
|
||||
## TypeScript Example
|
||||
|
||||
```bash
|
||||
export SANDBOX_TOKEN="..."
|
||||
```typescript
|
||||
import { Sandbox } from "@e2b/code-interpreter";
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
|
||||
# Install sandbox-agent binary (or build from source)
|
||||
# TODO: replace with release download once published
|
||||
cargo run -p sandbox-agent -- server \
|
||||
--token "$SANDBOX_TOKEN" \
|
||||
--host 0.0.0.0 \
|
||||
--port 2468
|
||||
// Pass API keys to the sandbox
|
||||
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 sandbox = await Sandbox.create({ envs });
|
||||
|
||||
// Install sandbox-agent
|
||||
await sandbox.commands.run(
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"
|
||||
);
|
||||
|
||||
// Start the server in the background
|
||||
await sandbox.commands.run(
|
||||
"sandbox-agent server --no-token --host 0.0.0.0 --port 3000",
|
||||
{ background: true }
|
||||
);
|
||||
|
||||
// Connect to the server
|
||||
const baseUrl = `https://${sandbox.getHost(3000)}`;
|
||||
const client = await SandboxAgent.connect({ baseUrl });
|
||||
|
||||
// Wait for server to be ready
|
||||
for (let i = 0; i < 30; i++) {
|
||||
try {
|
||||
await client.getHealth();
|
||||
break;
|
||||
} catch {
|
||||
await new Promise((r) => setTimeout(r, 1000));
|
||||
}
|
||||
}
|
||||
|
||||
// Install agents (or pre-install in a custom template)
|
||||
await client.installAgent("claude");
|
||||
await client.installAgent("codex");
|
||||
|
||||
// Create a session and start coding
|
||||
await client.createSession("my-session", {
|
||||
agent: "claude",
|
||||
permissionMode: "default",
|
||||
});
|
||||
|
||||
await client.postMessage("my-session", {
|
||||
message: "Summarize this repository",
|
||||
});
|
||||
|
||||
for await (const event of client.streamEvents("my-session")) {
|
||||
console.log(event.type, event.data);
|
||||
}
|
||||
|
||||
// Cleanup
|
||||
await sandbox.kill();
|
||||
```
|
||||
|
||||
4. Configure your client to connect to the sandbox endpoint.
|
||||
## Faster Cold Starts
|
||||
|
||||
For faster startup, create a custom E2B template with sandbox-agent and agents pre-installed:
|
||||
|
||||
1. Create a template with the install script baked in
|
||||
2. Pre-install agents: `sandbox-agent install-agent claude codex`
|
||||
3. Use the template ID when creating sandboxes
|
||||
|
||||
See [E2B Custom Templates](https://e2b.dev/docs/sandbox-template) for details.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,21 @@
|
|||
---
|
||||
sidebarTitle: Overview
|
||||
title: "Deploy"
|
||||
sidebarTitle: "Overview"
|
||||
description: "Choose where to run the sandbox-agent server."
|
||||
icon: "server"
|
||||
---
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Local" icon="laptop" href="/deploy/local">
|
||||
Run locally for development. The SDK can auto-spawn the server.
|
||||
</Card>
|
||||
<Card title="E2B" icon="cube" href="/deploy/e2b">
|
||||
Deploy inside an E2B sandbox with network access.
|
||||
</Card>
|
||||
<Card title="Daytona" icon="cloud" href="/deploy/daytona">
|
||||
Run in a Daytona workspace with port forwarding.
|
||||
</Card>
|
||||
<Card title="Docker" icon="docker" href="/deploy/docker">
|
||||
Build and run in a container (development only).
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
|
|||
43
docs/deploy/local.mdx
Normal file
43
docs/deploy/local.mdx
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: "Local"
|
||||
description: "Run the daemon locally for development."
|
||||
---
|
||||
|
||||
For local development, you can run the daemon directly on your machine.
|
||||
|
||||
## With the CLI
|
||||
|
||||
```bash
|
||||
# Install
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
|
||||
|
||||
# Run
|
||||
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
|
||||
```
|
||||
|
||||
Or with npm:
|
||||
|
||||
```bash
|
||||
npx sandbox-agent server --no-token --host 127.0.0.1 --port 2468
|
||||
```
|
||||
|
||||
## With the TypeScript SDK
|
||||
|
||||
The SDK can automatically spawn and manage the server as a subprocess:
|
||||
|
||||
```typescript
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
|
||||
// Spawns sandbox-agent server as a subprocess
|
||||
const client = await SandboxAgent.start();
|
||||
|
||||
await client.createSession("my-session", {
|
||||
agent: "claude",
|
||||
permissionMode: "default",
|
||||
});
|
||||
|
||||
// When done
|
||||
await client.dispose();
|
||||
```
|
||||
|
||||
This installs the binary (if needed) and starts the server on a random available port. No manual setup required.
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
---
|
||||
title: "Vercel Sandboxes"
|
||||
description: "Run the daemon inside Vercel Sandboxes."
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
1. Provision a Vercel Sandbox with network access and storage.
|
||||
2. Install the agent binaries you need.
|
||||
3. Run the daemon and expose the port.
|
||||
|
||||
```bash
|
||||
export SANDBOX_TOKEN="..."
|
||||
|
||||
cargo run -p sandbox-agent -- server \
|
||||
--token "$SANDBOX_TOKEN" \
|
||||
--host 0.0.0.0 \
|
||||
--port 2468
|
||||
```
|
||||
|
||||
4. Configure your client to use the sandbox URL.
|
||||
Loading…
Add table
Add a link
Reference in a new issue