harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 05:02:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: documentation overhaul and universal schema reference (#10)

Browse source 
* 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 2026-01-28 05:07:15 -08:00 • committed by GitHub
parent a6f77f3008
commit 08d299a3ef
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
40 changed files with 1996 additions and 1004 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
.github/media/inspector.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.1 MiB

6
CLAUDE.md
View file

@ -30,6 +30,7 @@ Universal schema guidance:
- Keep CLI subcommands in sync with every HTTP endpoint.
- Update `CLAUDE.md` to keep CLI endpoints in sync with HTTP API changes.
- When adding or modifying CLI commands, update `docs/cli.mdx` to reflect the changes.
- When changing the HTTP API, update the TypeScript SDK and CLI together.
- Do not make breaking changes to API endpoints.
- When changing API routes, ensure the HTTP/SSE test suite has full coverage of every route.
@ -39,10 +40,10 @@ Universal schema guidance:
- Never use synthetic data or mocked responses in tests.
- Never manually write agent types; always use generated types in `resources/agent-schemas/`. If types are broken, fix the generated types.
- The universal schema must provide consistent behavior across providers; avoid requiring frontend/client logic to special-case agents.
- The UI must reflect every field in AgentCapabilities; keep it in sync with the README feature matrix and `agent_capabilities_for`.
- The UI must reflect every field in AgentCapabilities; keep it in sync with the README feature matrix, `docs/agent-compatibility.mdx`, and `agent_capabilities_for`.
- When parsing agent data, if something is unexpected or does not match the schema, bail out and surface the error rather than trying to continue with partial parsing.
- When defining the universal schema, choose the option most compatible with native agent APIs, and add synthetics to fill gaps for other agents.
- Use `docs/glossary.md` as the source of truth for universal schema terminology and keep it updated alongside schema changes.
- Use `docs/universal-schema.mdx` as the source of truth for universal schema terminology and keep it updated alongside schema changes.
- On parse failures, emit an `agent.unparsed` event (source=daemon, synthetic=true) and treat it as a test failure. Preserve raw payloads when `include_raw=true`.
- Track subagent support in `docs/conversion.md`. For now, normalize subagent activity into normal message/tool flow, but revisit explicit subagent modeling later.
- Keep the FAQ in `README.md` and `frontend/packages/website/src/components/FAQ.tsx` in sync. When adding or modifying FAQ entries, update both files.
@ -56,6 +57,7 @@ Universal schema guidance:
- `sandbox-agent api sessions create` ↔ `POST /v1/sessions/{sessionId}`
- `sandbox-agent api sessions send-message` ↔ `POST /v1/sessions/{sessionId}/messages`
- `sandbox-agent api sessions send-message-stream` ↔ `POST /v1/sessions/{sessionId}/messages/stream`
- `sandbox-agent api sessions terminate` ↔ `POST /v1/sessions/{sessionId}/terminate`
- `sandbox-agent api sessions events` / `get-messages` ↔ `GET /v1/sessions/{sessionId}/events`
- `sandbox-agent api sessions events-sse` ↔ `GET /v1/sessions/{sessionId}/events/sse`
- `sandbox-agent api sessions reply-question` ↔ `POST /v1/sessions/{sessionId}/questions/{questionId}/reply`

59
README.md
View file

@ -9,11 +9,11 @@
- **Any coding agent**: Universal API to interact with all agents with full feature coverage
- **Server or SDK mode**: Run as an HTTP server or with the TypeScript SDK
- **Universal session schema**: Universal schema to store agent transcripts
- **Universal session schema**: [Universal schema](https://sandboxagent.dev/docs/universal-schema) to store agent transcripts
- **Supports your sandbox provider**: Daytona, E2B, Vercel Sandboxes, and more
- **Lightweight, portable Rust binary**: Install anywhere with 1 curl command
- **Automatic agent installation**: Agents are installed on-demand when first used
- **OpenAPI spec**: https://sandboxagent.dev/docs/api
- **OpenAPI spec**: Well documented and easy to integrate
[Documentation](https://sandboxagent.dev/docs) — [Discord](https://rivet.dev/discord)
@ -37,7 +37,7 @@
| MCP Tools | | ✓ | | |
| Streaming Deltas | | ✓ | ✓ | |
* Claude headless CLI does not natively support tool calls/results or HITL questions/permissions yet; these are WIP.
\* Coming imminently
Want support for another agent? [Open an issue](https://github.com/anthropics/sandbox-agent/issues/new) to request it.
@ -116,7 +116,7 @@ for await (const event of client.streamEvents("demo", { offset: 0 })) {
}
```
[Documentation](https://sandboxagent.dev/docs/sdks/typescript)
[Documentation](https://sandboxagent.dev/docs/sdks/typescript) — [Building a Chat UI](https://sandboxagent.dev/docs/building-chat-ui) — [Managing Sessions](https://sandboxagent.dev/docs/manage-sessions)
### Server
@ -144,8 +144,7 @@ To disable auth locally:
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
```
[Documentation](https://sandboxagent.dev/docs/quickstart)
[Integration guides](https://sandboxagent.dev/docs/deployments)
[Documentation](https://sandboxagent.dev/docs/quickstart) - [Integration guides](https://sandboxagent.dev/docs/deploy)
### CLI
@ -169,7 +168,23 @@ You can also use npx like:
npx sandbox-agent --help
```
[Documentation](https://rivet.dev/docs/cli)
[Documentation](https://sandboxagent.dev/docs/cli)
### Inspector
Debug sessions and events with the [Inspector UI](https://inspect.sandboxagent.dev).
![Sandbox Agent Inspector](./.github/media/inspector.png)
[Documentation](https://sandboxagent.dev/docs/inspector)
### OpenAPI Specification
[Explore API](https://sandboxagent.dev/docs/api-reference) — [View Specification](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json)
### Universal Schema
All events follow a [universal schema](https://sandboxagent.dev/docs/universal-schema) that normalizes differences between agents.
### Tip: Extract credentials
@ -183,33 +198,47 @@ This prints environment variables for your OpenAI/Anthropic/etc API keys to test
## FAQ
**Does this replace the Vercel AI SDK?**
<details>
<summary><strong>Does this replace the Vercel AI SDK?</strong></summary>
No, they're complementary. AI SDK is for building chat interfaces and calling LLMs. This SDK is for controlling autonomous coding agents that write code and run commands. Use AI SDK for your UI, use this when you need an agent to actually code.
</details>
**Which coding agents are supported?**
<details>
<summary><strong>Which coding agents are supported?</strong></summary>
Claude Code, Codex, OpenCode, and Amp. The SDK normalizes their APIs so you can swap between them without changing your code.
</details>
**How is session data persisted?**
<details>
<summary><strong>How is session data persisted?</strong></summary>
This SDK does not handle persisting session data. Events stream in a universal JSON schema that you can persist anywhere. Consider using Postgres or [Rivet Actors](https://rivet.gg) for data persistence.
This SDK does not handle persisting session data. Events stream in a universal JSON schema that you can persist anywhere. See [Managing Sessions](https://sandboxagent.dev/docs/manage-sessions) for patterns using Postgres or [Rivet Actors](https://rivet.gg).
</details>
**Can I run this locally or does it require a sandbox provider?**
<details>
<summary><strong>Can I run this locally or does it require a sandbox provider?</strong></summary>
Both. Run locally for development, deploy to E2B, Daytona, or Vercel Sandboxes for production.
</details>
**Does it support [platform]?**
<details>
<summary><strong>Does it support [platform]?</strong></summary>
The server is a single Rust binary that runs anywhere with a curl install. If your platform can run Linux binaries (Docker, VMs, etc.), it works. See the deployment guides for E2B, Daytona, and Vercel Sandboxes.
</details>
**Can I use this with my personal API keys?**
<details>
<summary><strong>Can I use this with my personal API keys?</strong></summary>
Yes. Use `sandbox-agent credentials extract-env` to extract API keys from your local agent configs (Claude Code, Codex, OpenCode, Amp) and pass them to the sandbox environment.
</details>
**Why Rust and not [language]?**
<details>
<summary><strong>Why Rust and not [language]?</strong></summary>
Rust gives us a single static binary, fast startup, and predictable memory usage. That makes it easy to run inside sandboxes or in CI without shipping a large runtime, such as Node.js.
</details>
## Project Goals

104
docs/agent-compatibility.mdx
View file

@ -1,28 +1,96 @@
---
title: "Agent Compatibility"
description: "Supported agents, install methods, and streaming formats."
description: "Feature support across coding agents."
icon: "table"
---
## Compatibility matrix
The universal API normalizes different coding agents into a consistent interface. Each agent has different native capabilities; the daemon fills gaps with synthetic events where possible.
| Agent | Provider | Binary | Install method | Session ID | Streaming format |
|-------|----------|--------|----------------|------------|------------------|
| Claude Code | Anthropic | `claude` | curl raw binary from GCS | `session_id` | JSONL via stdout |
| Codex | OpenAI | `codex` | curl tarball from GitHub releases | `thread_id` | JSON-RPC over stdio |
| OpenCode | Multi-provider | `opencode` | curl tarball from GitHub releases | `session_id` | SSE or JSONL |
| Amp | Sourcegraph | `amp` | curl raw binary from GCS | `session_id` | JSONL via stdout |
| Mock | Built-in | — | bundled | `mock-*` | daemon-generated |
## Feature Matrix
## Agent modes
| Feature | [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)* | [Codex](https://github.com/openai/codex) | [OpenCode](https://github.com/opencode-ai/opencode) | [Amp](https://ampcode.com) |
|---------|:-----------:|:-----:|:--------:|:---:|
| Stability | Stable | Stable | Experimental | Experimental |
| Text Messages | ✓ | ✓ | ✓ | ✓ |
| Tool Calls | —* | ✓ | ✓ | ✓ |
| Tool Results | —* | ✓ | ✓ | ✓ |
| Questions (HITL) | —* | | ✓ | |
| Permissions (HITL) | —* | | ✓ | |
| Images | | ✓ | ✓ | |
| File Attachments | | ✓ | ✓ | |
| Session Lifecycle | | ✓ | ✓ | |
| Error Events | | ✓ | ✓ | ✓ |
| Reasoning/Thinking | | ✓ | | |
| Command Execution | | ✓ | | |
| File Changes | | ✓ | | |
| MCP Tools | | ✓ | | |
| Streaming Deltas | | ✓ | ✓ | |
- **OpenCode**: discovered via the server API.
- **Claude Code / Codex / Amp**: hardcoded modes (typically `build`, `plan`, or `custom`).
\* Coming imminently
## Capability notes
## Feature Descriptions
- **Questions / permissions**: OpenCode natively supports these workflows. Claude plan approval is normalized into a question event (tests do not currently exercise Claude question/permission flows).
- **Streaming**: all agents stream events; OpenCode uses SSE, Codex uses JSON-RPC over stdio, others use JSONL. Codex is currently normalized to thread/turn starts plus user/assistant completed items (deltas and tool/reasoning items are not emitted yet).
- **User messages**: Claude CLI output does not include explicit user-message events in our snapshots, so only assistant messages are surfaced for Claude today.
- **Files and images**: normalized via `UniversalMessagePart` with `File` and `Image` parts.
### Text Messages
See [Universal API](/universal-api) for feature coverage details.
Basic message exchange between user and assistant.
### Tool Calls & Results
Visibility into tool invocations (file reads, command execution, etc.) and their results. When not natively supported, tool activity is embedded in message content.
### Questions (HITL)
Interactive questions the agent asks the user. Emits `question.requested` and `question.resolved` events.
### Permissions (HITL)
Permission requests for sensitive operations. Emits `permission.requested` and `permission.resolved` events.
### Images
Support for image attachments in messages.
### File Attachments
Support for file attachments in messages.
### Session Lifecycle
Native `session.started` and `session.ended` events. When not supported, the daemon emits synthetic lifecycle events.
### Error Events
Structured error events for runtime failures.
### Reasoning/Thinking
Extended thinking or reasoning content with visibility controls.
### Command Execution
Detailed command execution events with stdout/stderr.
### File Changes
Structured file modification events with diffs.
### MCP Tools
Model Context Protocol tool support.
### Streaming Deltas
Native streaming of content deltas. When not supported, the daemon emits a single synthetic delta before `item.completed`.
## Synthetic Events
For features not natively supported, the daemon generates synthetic events to maintain a consistent event stream. Synthetic events have:
- `source: "daemon"`
- `synthetic: true`
This lets you build UIs that work with any agent without special-casing each provider.
## Request Support
Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it.

443
docs/building-chat-ui.mdx
View file

@ -1,57 +1,76 @@
---
title: "Building a Chat UI"
description: "Design a client that renders universal session events consistently across providers."
description: "Build a chat interface using the universal event stream."
icon: "comments"
---
This guide explains how to build a chat UI that works across all agents using the universal event
stream.
## Setup
## High-level flow
### List agents
1. List agents and read their capabilities.
2. Create a session for the selected agent.
3. Send user messages.
4. Subscribe to events (polling or SSE).
5. Render items and deltas into a stable message timeline.
```ts
const { agents } = await client.listAgents();
## Use agent capabilities
// Each agent has capabilities that determine what UI to show
const claude = agents.find((a) => a.id === "claude");
if (claude?.capabilities.permissions) {
// Show permission approval UI
}
if (claude?.capabilities.questions) {
// Show question response UI
}
```
Capabilities tell you which features are supported for the selected agent:
### Create a session
- `tool_calls` and `tool_results` indicate tool execution events.
- `questions` and `permissions` indicate HITL flows.
- `plan_mode` indicates that the agent supports plan-only execution.
- `reasoning` and `status` indicate that the agent can emit reasoning/status content parts.
- `item_started` indicates that the agent emits `item.started` on its own; when false the daemon will emit a synthetic `item.started` immediately after sending a user message.
```ts
const sessionId = `session-${crypto.randomUUID()}`;
Use these to enable or disable UI affordances (tool panels, approval buttons, etc.).
await client.createSession(sessionId, {
agent: "claude",
agentMode: "code", // Optional: agent-specific mode
permissionMode: "default", // Optional: "default" | "plan" | "bypass"
model: "claude-sonnet-4", // Optional: model override
});
```
## Event model
### Send a message
Every event includes:
```ts
await client.postMessage(sessionId, { message: "Hello, world!" });
```
- `event_id`, `sequence`, and `time` for ordering.
- `session_id` for the universal session.
- `native_session_id` for provider-specific debugging.
- `type` with one of:
- `session.started`, `session.ended`
- `item.started`, `item.delta`, `item.completed`
- `permission.requested`, `permission.resolved`
- `question.requested`, `question.resolved`
- `error`, `agent.unparsed`
- `data` which holds the payload for the event type.
- `synthetic` and `source` to show daemon-generated events.
- `raw` (optional) when `include_raw=true`.
### Stream events
## Rendering items
Three options for receiving events:
Items are emitted in three phases:
```ts
// Option 1: SSE (recommended for real-time UI)
const stream = client.streamEvents(sessionId, { offset: 0 });
for await (const event of stream) {
handleEvent(event);
}
- `item.started`: first snapshot of a message or tool item.
- `item.delta`: incremental updates (token streaming or synthetic deltas).
- `item.completed`: final snapshot.
// Option 2: Polling
const { events, hasMore } = await client.getEvents(sessionId, { offset: 0 });
events.forEach(handleEvent);
Recommended render flow:
// Option 3: Turn streaming (send + stream in one call)
const stream = client.streamTurn(sessionId, { message: "Hello" });
for await (const event of stream) {
handleEvent(event);
}
```
Use `offset` to track the last seen `sequence` number and resume from where you left off.
---
## Handling Events
### Bare minimum
Handle these three events to render a basic chat:
```ts
type ItemState = {
@ -60,108 +79,278 @@ type ItemState = {
};
const items = new Map<string, ItemState>();
const order: string[] = [];
function applyEvent(event: UniversalEvent) {
if (event.type === "item.started") {
const item = event.data.item;
items.set(item.item_id, { item, deltas: [] });
order.push(item.item_id);
}
if (event.type === "item.delta") {
const { item_id, delta } = event.data;
const state = items.get(item_id);
if (state) {
state.deltas.push(delta);
function handleEvent(event: UniversalEvent) {
switch (event.type) {
case "item.started": {
const { item } = event.data as ItemEventData;
items.set(item.item_id, { item, deltas: [] });
break;
}
}
if (event.type === "item.completed") {
const item = event.data.item;
const state = items.get(item.item_id);
if (state) {
state.item = item;
case "item.delta": {
const { item_id, delta } = event.data as ItemDeltaData;
const state = items.get(item_id);
if (state) {
state.deltas.push(delta);
}
break;
}
case "item.completed": {
const { item } = event.data as ItemEventData;
const state = items.get(item.item_id);
if (state) {
state.item = item;
state.deltas = []; // Clear deltas, use final content
}
break;
}
}
}
```
When rendering, combine the item content with accumulated deltas. If you receive a delta before a
started event (should not happen), treat it as an error.
When rendering, show a loading indicator while `item.status === "in_progress"`:
## Content parts
```ts
function renderItem(state: ItemState) {
const { item, deltas } = state;
const isLoading = item.status === "in_progress";
Each `UniversalItem` has `content` parts. Your UI can branch on `part.type`:
// For streaming text, combine item content with accumulated deltas
const text = item.content
.filter((p) => p.type === "text")
.map((p) => p.text)
.join("");
const streamedText = text + deltas.join("");
- `text` for normal chat text.
- `tool_call` and `tool_result` for tool execution.
- `file_ref` for file read/write/patch previews.
- `reasoning` if you display public reasoning text.
- `status` for progress updates.
- `image` for image outputs.
Treat `item.kind` as the primary layout decision (message vs tool call vs system), and use content
parts for the detailed rendering.
## Questions and permissions
Question and permission events are out-of-band from item flow. Render them as modal or inline UI
blocks that must be resolved via:
- `POST /v1/sessions/{session_id}/questions/{question_id}/reply`
- `POST /v1/sessions/{session_id}/questions/{question_id}/reject`
- `POST /v1/sessions/{session_id}/permissions/{permission_id}/reply`
If an agent does not advertise these capabilities, keep those UI controls hidden.
## Error and unparsed events
- `error` events are structured failures from the daemon or agent.
- `agent.unparsed` indicates the provider emitted something the converter could not parse.
Treat `agent.unparsed` as a hard failure in development so you can fix converters quickly.
## Event ordering
Prefer `sequence` for ordering. It is monotonic for a given session. The `time` field is for
timestamps, not ordering.
## Handling session end
`session.ended` includes the reason and who terminated it. Disable input after a terminal event.
## Optional raw payloads
If you need provider-level debugging, pass `include_raw=true` when streaming or polling events
(including one-turn streams) to receive the `raw` payload for each event.
## SSE vs polling vs turn streaming
- SSE gives low-latency updates and simplifies streaming UIs.
- Polling is simpler to debug and works in any environment.
- Turn streaming (`POST /v1/sessions/{session_id}/messages/stream`) is a one-shot stream tied to a
single prompt. The stream closes automatically once the turn completes.
Both yield the same event payloads.
## Mock agent for UI testing
Use the built-in `mock` agent to exercise UI behaviors without external credentials:
```bash
curl -X POST http://127.0.0.1:2468/v1/sessions/demo-session \
-H "content-type: application/json" \
-d '{"agent":"mock"}'
return {
content: streamedText,
isLoading,
role: item.role,
kind: item.kind,
};
}
```
The mock agent sends a prompt telling you what commands it accepts. Send messages like `demo`,
`markdown`, or `permission` to emit specific event sequences. Any other text is echoed back as an
assistant message so you can test rendering, streaming, and approval flows on demand.
### Extra events
## Reference implementation
Handle these for a complete implementation:
The [Inspector chat UI](https://github.com/rivet-dev/sandbox-agent/blob/main/frontend/packages/inspector/src/App.tsx)
is a complete reference implementation showing how to build a chat interface using the universal event
stream. It demonstrates session management, event rendering, item lifecycle handling, and HITL approval
flows.
```ts
function handleEvent(event: UniversalEvent) {
switch (event.type) {
// ... bare minimum events above ...
case "session.started": {
// Session is ready
break;
}
case "session.ended": {
const { reason, terminated_by } = event.data as SessionEndedData;
// Disable input, show end reason
// reason: "completed" | "error" | "terminated"
// terminated_by: "agent" | "daemon"
break;
}
case "error": {
const { message, code } = event.data as ErrorData;
// Display error to user
break;
}
case "agent.unparsed": {
const { error, location } = event.data as AgentUnparsedData;
// Parsing failure - treat as bug in development
console.error(`Parse error at ${location}: ${error}`);
break;
}
}
}
```
### Content parts
Each item has `content` parts. Render based on `type`:
```ts
function renderContentPart(part: ContentPart) {
switch (part.type) {
case "text":
return <Markdown>{part.text}</Markdown>;
case "tool_call":
return <ToolCall name={part.name} args={part.arguments} />;
case "tool_result":
return <ToolResult output={part.output} />;
case "file_ref":
return <FileChange path={part.path} action={part.action} diff={part.diff} />;
case "reasoning":
return <Reasoning>{part.text}</Reasoning>;
case "status":
return <Status label={part.label} detail={part.detail} />;
case "image":
return <Image src={part.path} />;
}
}
```
---
## Handling Permissions
When `permission.requested` arrives, show an approval UI:
```ts
const pendingPermissions = new Map<string, PermissionEventData>();
function handleEvent(event: UniversalEvent) {
if (event.type === "permission.requested") {
const data = event.data as PermissionEventData;
pendingPermissions.set(data.permission_id, data);
}
if (event.type === "permission.resolved") {
const data = event.data as PermissionEventData;
pendingPermissions.delete(data.permission_id);
}
}
// User clicks approve/deny
async function replyPermission(id: string, reply: "once" | "always" | "reject") {
await client.replyPermission(sessionId, id, { reply });
pendingPermissions.delete(id);
}
```
Render permission requests:
```ts
function PermissionRequest({ data }: { data: PermissionEventData }) {
return (
<div>
<p>Allow: {data.action}</p>
<button onClick={() => replyPermission(data.permission_id, "once")}>
Allow Once
</button>
<button onClick={() => replyPermission(data.permission_id, "always")}>
Always Allow
</button>
<button onClick={() => replyPermission(data.permission_id, "reject")}>
Reject
</button>
</div>
);
}
```
---
## Handling Questions
When `question.requested` arrives, show a selection UI:
```ts
const pendingQuestions = new Map<string, QuestionEventData>();
function handleEvent(event: UniversalEvent) {
if (event.type === "question.requested") {
const data = event.data as QuestionEventData;
pendingQuestions.set(data.question_id, data);
}
if (event.type === "question.resolved") {
const data = event.data as QuestionEventData;
pendingQuestions.delete(data.question_id);
}
}
// User selects answer(s)
async function answerQuestion(id: string, answers: string[][]) {
await client.replyQuestion(sessionId, id, { answers });
pendingQuestions.delete(id);
}
async function rejectQuestion(id: string) {
await client.rejectQuestion(sessionId, id);
pendingQuestions.delete(id);
}
```
Render question requests:
```ts
function QuestionRequest({ data }: { data: QuestionEventData }) {
const [selected, setSelected] = useState<string[]>([]);
return (
<div>
<p>{data.prompt}</p>
{data.options.map((option) => (
<label key={option}>
<input
type="checkbox"
checked={selected.includes(option)}
onChange={(e) => {
if (e.target.checked) {
setSelected([...selected, option]);
} else {
setSelected(selected.filter((s) => s !== option));
}
}}
/>
{option}
</label>
))}
<button onClick={() => answerQuestion(data.question_id, [selected])}>
Submit
</button>
<button onClick={() => rejectQuestion(data.question_id)}>
Reject
</button>
</div>
);
}
```
---
## Testing with Mock Agent
The `mock` agent lets you test UI behaviors without external credentials:
```ts
await client.createSession("test-session", { agent: "mock" });
```
Send `help` to see available commands:
| Command | Tests |
|---------|-------|
| `help` | Lists all commands |
| `demo` | Full UI coverage sequence with markers |
| `markdown` | Streaming markdown rendering |
| `tool` | Tool call + result with file refs |
| `status` | Status item updates |
| `image` | Image content part |
| `permission` | Permission request flow |
| `question` | Question request flow |
| `error` | Error + unparsed events |
| `end` | Session ended event |
| `echo <text>` | Echo text as assistant message |
Any unrecognized text is echoed back as an assistant message.
---
## Reference Implementation
The [Inspector UI](https://github.com/rivet-dev/sandbox-agent/blob/main/frontend/packages/inspector/src/App.tsx)
is a complete reference showing session management, event rendering, and HITL flows.

318
docs/cli.mdx
View file

@ -1,140 +1,310 @@
---
title: "CLI"
description: "CLI reference and server flags."
title: "CLI Reference"
description: "Complete CLI reference for sandbox-agent."
sidebarTitle: "CLI"
icon: "terminal"
---
The `sandbox-agent api` subcommand mirrors the HTTP API so you can script everything without writing client code.
## Server
## Server flags
Start the HTTP server:
```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
sandbox-agent server [OPTIONS]
```
- `--token`: global token for all requests.
- `--no-token`: disable auth (local dev only).
- `--host`, `--port`: bind address.
- `--cors-allow-origin`, `--cors-allow-method`, `--cors-allow-header`, `--cors-allow-credentials`: configure CORS.
- `--no-telemetry`: disable anonymous telemetry.
| Option | Default | Description |
|--------|---------|-------------|
| `-t, --token <TOKEN>` | - | Authentication token for all requests |
| `-n, --no-token` | - | Disable authentication (local dev only) |
| `-H, --host <HOST>` | `127.0.0.1` | Host to bind to |
| `-p, --port <PORT>` | `2468` | Port to bind to |
| `-O, --cors-allow-origin <ORIGIN>` | - | CORS allowed origin (repeatable) |
| `-M, --cors-allow-method <METHOD>` | - | CORS allowed method (repeatable) |
| `-A, --cors-allow-header <HEADER>` | - | CORS allowed header (repeatable) |
| `-C, --cors-allow-credentials` | - | Enable CORS credentials |
| `--no-telemetry` | - | Disable anonymous telemetry |
## Install agent (no server required)
```bash
sandbox-agent server --token "$TOKEN" --port 3000
```
<details>
<summary><strong>install-agent</strong></summary>
---
## Install Agent (Local)
Install an agent without running the server:
```bash
sandbox-agent install-agent <AGENT> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-r, --reinstall` | Force reinstall even if already installed |
```bash
sandbox-agent install-agent claude --reinstall
```
</details>
## API agent commands
---
<details>
<summary><strong>api agents list</strong></summary>
## Credentials
### Extract
Extract locally discovered credentials:
```bash
sandbox-agent api agents list --endpoint http://127.0.0.1:2468
sandbox-agent credentials extract [OPTIONS]
```
</details>
<details>
<summary><strong>api agents install</strong></summary>
| Option | Description |
|--------|-------------|
| `-a, --agent <AGENT>` | Filter by agent (`claude`, `codex`, `opencode`, `amp`) |
| `-p, --provider <PROVIDER>` | Filter by provider (`anthropic`, `openai`) |
| `-d, --home-dir <DIR>` | Custom home directory for credential search |
| `-r, --reveal` | Show full credential values (default: redacted) |
| `--no-oauth` | Exclude OAuth credentials |
```bash
sandbox-agent api agents install claude --reinstall --endpoint http://127.0.0.1:2468
sandbox-agent credentials extract --agent claude --reveal
sandbox-agent credentials extract --provider anthropic
```
</details>
<details>
<summary><strong>api agents modes</strong></summary>
### Extract as Environment Variables
Output credentials as shell environment variables:
```bash
sandbox-agent api agents modes claude --endpoint http://127.0.0.1:2468
sandbox-agent credentials extract-env [OPTIONS]
```
</details>
## API session commands
<details>
<summary><strong>api sessions list</strong></summary>
| Option | Description |
|--------|-------------|
| `-e, --export` | Prefix each line with `export` |
| `-d, --home-dir <DIR>` | Custom home directory for credential search |
| `--no-oauth` | Exclude OAuth credentials |
```bash
sandbox-agent api sessions list --endpoint http://127.0.0.1:2468
# Source directly into shell
eval "$(sandbox-agent credentials extract-env --export)"
```
</details>
<details>
<summary><strong>api sessions create</strong></summary>
---
## API Commands
The `sandbox-agent api` subcommand mirrors the HTTP API for scripting without client code.
All API commands support:
| Option | Default | Description |
|--------|---------|-------------|
| `-e, --endpoint <URL>` | `http://127.0.0.1:2468` | API endpoint |
| `-t, --token <TOKEN>` | - | Authentication token |
---
### Agents
#### List Agents
```bash
sandbox-agent api agents list
```
#### Install Agent
```bash
sandbox-agent api agents install <AGENT> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-r, --reinstall` | Force reinstall |
```bash
sandbox-agent api agents install claude --reinstall
```
#### Get Agent Modes
```bash
sandbox-agent api agents modes <AGENT>
```
```bash
sandbox-agent api agents modes claude
```
---
### Sessions
#### List Sessions
```bash
sandbox-agent api sessions list
```
#### Create Session
```bash
sandbox-agent api sessions create <SESSION_ID> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-a, --agent <AGENT>` | Agent identifier (required) |
| `-g, --agent-mode <MODE>` | Agent mode |
| `-p, --permission-mode <MODE>` | Permission mode (`default`, `plan`, `bypass`) |
| `-m, --model <MODEL>` | Model override |
| `-v, --variant <VARIANT>` | Model variant |
| `-A, --agent-version <VERSION>` | Agent version |
```bash
sandbox-agent api sessions create my-session \
--agent claude \
--agent-mode build \
--permission-mode default \
--endpoint http://127.0.0.1:2468
--agent-mode code \
--permission-mode default
```
</details>
<details>
<summary><strong>api sessions send-message</strong></summary>
#### Send Message
```bash
sandbox-agent api sessions send-message <SESSION_ID> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-m, --message <TEXT>` | Message text (required) |
```bash
sandbox-agent api sessions send-message my-session \
--message "Summarize the repository" \
--endpoint http://127.0.0.1:2468
--message "Summarize the repository"
```
</details>
<details>
<summary><strong>api sessions send-message-stream</strong></summary>
#### Send Message (Streaming)
Send a message and stream the response:
```bash
sandbox-agent api sessions send-message-stream <SESSION_ID> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-m, --message <TEXT>` | Message text (required) |
| `--include-raw` | Include raw agent data |
```bash
sandbox-agent api sessions send-message-stream my-session \
--message "Summarize the repository" \
--endpoint http://127.0.0.1:2468
--message "Help me debug this"
```
</details>
<details>
<summary><strong>api sessions events</strong></summary>
#### Terminate Session
```bash
sandbox-agent api sessions events my-session --offset 0 --limit 50 --endpoint http://127.0.0.1:2468
sandbox-agent api sessions terminate <SESSION_ID>
```
</details>
<details>
<summary><strong>api sessions events-sse</strong></summary>
```bash
sandbox-agent api sessions events-sse my-session --offset 0 --endpoint http://127.0.0.1:2468
sandbox-agent api sessions terminate my-session
```
</details>
<details>
<summary><strong>api sessions reply-question</strong></summary>
#### Get Events
Fetch session events:
```bash
sandbox-agent api sessions reply-question my-session QUESTION_ID \
--answers "yes" \
--endpoint http://127.0.0.1:2468
sandbox-agent api sessions events <SESSION_ID> [OPTIONS]
```
</details>
<details>
<summary><strong>api sessions reject-question</strong></summary>
| Option | Description |
|--------|-------------|
| `-o, --offset <N>` | Event offset |
| `-l, --limit <N>` | Max events to return |
| `--include-raw` | Include raw agent data |
```bash
sandbox-agent api sessions reject-question my-session QUESTION_ID --endpoint http://127.0.0.1:2468
sandbox-agent api sessions events my-session --offset 0 --limit 50
```
</details>
<details>
<summary><strong>api sessions reply-permission</strong></summary>
`get-messages` is an alias for `events`.
#### Stream Events (SSE)
Stream session events via Server-Sent Events:
```bash
sandbox-agent api sessions reply-permission my-session PERMISSION_ID \
--reply once \
--endpoint http://127.0.0.1:2468
sandbox-agent api sessions events-sse <SESSION_ID> [OPTIONS]
```
</details>
| Option | Description |
|--------|-------------|
| `-o, --offset <N>` | Event offset to start from |
| `--include-raw` | Include raw agent data |
```bash
sandbox-agent api sessions events-sse my-session --offset 0
```
#### Reply to Question
```bash
sandbox-agent api sessions reply-question <SESSION_ID> <QUESTION_ID> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-a, --answers <JSON>` | JSON array of answers (required) |
```bash
sandbox-agent api sessions reply-question my-session q1 \
--answers '[["yes"]]'
```
#### Reject Question
```bash
sandbox-agent api sessions reject-question <SESSION_ID> <QUESTION_ID>
```
```bash
sandbox-agent api sessions reject-question my-session q1
```
#### Reply to Permission
```bash
sandbox-agent api sessions reply-permission <SESSION_ID> <PERMISSION_ID> [OPTIONS]
```
| Option | Description |
|--------|-------------|
| `-r, --reply <REPLY>` | `once`, `always`, or `reject` (required) |
```bash
sandbox-agent api sessions reply-permission my-session perm1 --reply once
```
---
## CLI to HTTP Mapping
| CLI Command | HTTP Endpoint |
|-------------|---------------|
| `api agents list` | `GET /v1/agents` |
| `api agents install` | `POST /v1/agents/{agent}/install` |
| `api agents modes` | `GET /v1/agents/{agent}/modes` |
| `api sessions list` | `GET /v1/sessions` |
| `api sessions create` | `POST /v1/sessions/{sessionId}` |
| `api sessions send-message` | `POST /v1/sessions/{sessionId}/messages` |
| `api sessions send-message-stream` | `POST /v1/sessions/{sessionId}/messages/stream` |
| `api sessions terminate` | `POST /v1/sessions/{sessionId}/terminate` |
| `api sessions events` | `GET /v1/sessions/{sessionId}/events` |
| `api sessions events-sse` | `GET /v1/sessions/{sessionId}/events/sse` |
| `api sessions reply-question` | `POST /v1/sessions/{sessionId}/questions/{questionId}/reply` |
| `api sessions reject-question` | `POST /v1/sessions/{sessionId}/questions/{questionId}/reject` |
| `api sessions reply-permission` | `POST /v1/sessions/{sessionId}/permissions/{permissionId}/reply` |

60
docs/cors.mdx Normal file
View file

@ -0,0 +1,60 @@
---
title: "CORS Configuration"
description: "Configure CORS for browser-based applications."
sidebarTitle: "CORS"
icon: "globe"
---
When calling the Sandbox Agent server from a browser, you need to enable CORS (Cross-Origin Resource Sharing) explicitly.
## Basic Configuration
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "http://localhost:5173" \
--cors-allow-method "GET" \
--cors-allow-method "POST" \
--cors-allow-header "Authorization" \
--cors-allow-header "Content-Type" \
--cors-allow-credentials
```
## Options
| Flag | Description |
|------|-------------|
| `--cors-allow-origin` | Origins allowed to make requests (e.g., `http://localhost:5173`) |
| `--cors-allow-method` | HTTP methods to allow (can be specified multiple times) |
| `--cors-allow-header` | Headers to allow (can be specified multiple times) |
| `--cors-allow-credentials` | Allow credentials (cookies, authorization headers) |
## Multiple Origins
You can allow multiple origins by specifying the flag multiple times:
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "http://localhost:5173" \
--cors-allow-origin "http://localhost:3000" \
--cors-allow-method "GET" \
--cors-allow-method "POST" \
--cors-allow-header "Authorization" \
--cors-allow-header "Content-Type"
```
## Production
In production, replace `localhost` origins with your actual domain:
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "https://your-app.com" \
--cors-allow-method "GET" \
--cors-allow-method "POST" \
--cors-allow-header "Authorization" \
--cors-allow-header "Content-Type" \
--cors-allow-credentials
```

91
docs/deploy/daytona.mdx
View file

@ -3,19 +3,88 @@ title: "Daytona"
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.

80
docs/deploy/docker.mdx
View file

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

82
docs/deploy/e2b.mdx
View file

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

19
docs/deploy/index.mdx
View file

@ -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
View 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.

21
docs/deploy/vercel-sandboxes.mdx
View file

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

53
docs/docs.json
View file

@ -34,38 +34,43 @@
"pages": [
{
"group": "Getting started",
"pages": [
"index",
"quickstart",
"architecture",
"agent-compatibility",
"universal-api",
"frontend",
"building-chat-ui",
"manage-session-state"
]
},
{
"group": "SDKs",
"pages": ["sdks/typescript"]
},
{
"group": "AI",
"pages": ["ai/skill", "ai/llms-txt"]
},
{
"group": "Reference",
"pages": ["cli", "telemetry", "http-api"]
"pages": ["quickstart", "building-chat-ui", "manage-sessions"]
},
{
"group": "Deploy",
"pages": [
"deploy/index",
"deploy/docker",
"deploy/local",
"deploy/e2b",
"deploy/daytona",
"deploy/vercel-sandboxes"
"deploy/docker"
]
},
{
"group": "SDKs",
"pages": ["sdks/typescript", "sdks/python"]
},
{
"group": "Reference",
"pages": [
"cli",
"inspector",
"universal-schema",
"agent-compatibility",
"cors",
{
"group": "AI",
"pages": ["ai/skill", "ai/llms-txt"]
},
{
"group": "Advanced",
"pages": ["telemetry"]
}
]
},
{
"group": "HTTP API Reference",
"openapi": "openapi.json"
}
]
}

27
docs/favicon.svg
View file

@ -1,19 +1,10 @@
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M9.06145 23.1079C5.26816 22.3769 -3.39077 20.6274 1.4173 5.06384C9.6344 6.09939 16.9728 14.0644 9.06145 23.1079Z" fill="url(#paint0_linear_17557_2021)"/>
<path d="M8.91928 23.0939C5.27642 21.2223 0.78371 4.20891 17.0071 0C20.7569 7.19341 19.6212 16.5452 8.91928 23.0939Z" fill="url(#paint1_linear_17557_2021)"/>
<path d="M8.91388 23.0788C8.73534 19.8817 10.1585 9.08525 23.5699 13.1107C23.1812 20.1229 18.984 26.4182 8.91388 23.0788Z" fill="url(#paint2_linear_17557_2021)"/>
<defs>
<linearGradient id="paint0_linear_17557_2021" x1="3.77557" y1="5.91571" x2="5.23185" y2="21.5589" gradientUnits="userSpaceOnUse">
<stop stop-color="#18E299"/>
<stop offset="1" stop-color="#15803D"/>
</linearGradient>
<linearGradient id="paint1_linear_17557_2021" x1="12.1711" y1="-0.718425" x2="10.1897" y2="22.9832" gradientUnits="userSpaceOnUse">
<stop stop-color="#16A34A"/>
<stop offset="1" stop-color="#4ADE80"/>
</linearGradient>
<linearGradient id="paint2_linear_17557_2021" x1="23.1327" y1="15.353" x2="9.33841" y2="18.5196" gradientUnits="userSpaceOnUse">
<stop stop-color="#4ADE80"/>
<stop offset="1" stop-color="#0D9373"/>
</linearGradient>
</defs>
<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
<rect width="32" height="32" rx="6" fill="url(#bg_gradient)"/>
<text x="16" y="22" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="700" fill="white">SA</text>
<defs>
<linearGradient id="bg_gradient" x1="0" y1="0" x2="32" y2="32" gradientUnits="userSpaceOnUse">
<stop stop-color="#16A34A"/>
<stop offset="1" stop-color="#15803D"/>
</linearGradient>
</defs>
</svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.2 KiB

After

Width:  |  Height:  |  Size: 539 B

Before After
Before After

22
docs/frontend.mdx
View file

@ -1,22 +0,0 @@
---
title: "Frontend Demo"
description: "Run the Vite + React UI for testing the server."
---
The demo frontend lives at `frontend/packages/inspector`.
## Run locally
```bash
pnpm install
pnpm --filter @sandbox-agent/inspector dev
```
The UI expects:
- Endpoint (e.g. `http://127.0.0.1:2468`)
- Optional token
When running the server, the inspector is also served automatically at `http://127.0.0.1:2468/ui`.
If you see CORS errors, enable CORS on the server with `sandbox-agent server --cors-allow-origin` and related flags.

62
docs/glossary.md
View file

@ -1,62 +0,0 @@
# Glossary (Universal Schema)
This glossary defines the universal schema terms used across the daemon, SDK, and tests.
Session terms
- session_id: daemon-generated identifier for a universal session.
- native_session_id: provider-native thread/session/run identifier (thread_id merged here).
- session.started: event emitted at session start (native or synthetic).
- session.ended: event emitted at session end (native or synthetic); includes reason and terminated_by.
- terminated_by: who ended the session: agent or daemon.
- reason: why the session ended: completed, error, or terminated.
Event terms
- UniversalEvent: envelope that wraps all events; includes source, type, data, raw.
- event_id: unique identifier for the event.
- sequence: monotonic event sequence number within a session.
- time: RFC3339 timestamp for the event.
- source: event origin: agent (native) or daemon (synthetic).
- raw: original provider payload for native events; optional for synthetic events.
Item terms
- item_id: daemon-generated identifier for a universal item.
- native_item_id: provider-native item/message identifier when available; null otherwise.
- parent_id: item_id of the parent item (e.g., tool call/result parented to a message).
- kind: item category: message, tool_call, tool_result, system, status, unknown.
- role: actor role for message items: user, assistant, system, tool (or null).
- status: item lifecycle status: in_progress, completed, failed (or null).
Item event terms
- item.started: item creation event (may be synthetic).
- item.delta: streaming delta event (native where supported; synthetic otherwise).
- item.completed: final item event with complete content.
Content terms
- content: ordered list of parts that make up an item payload.
- content part: a typed element inside content (text, json, tool_call, tool_result, file_ref, image, status, reasoning).
- text: plain text content part.
- json: structured JSON content part.
- tool_call: tool invocation content part (name, arguments, call_id).
- tool_result: tool result content part (call_id, output).
- file_ref: file reference content part (path, action, diff).
- image: image content part (path, mime).
- status: status content part (label, detail).
- reasoning: reasoning content part (text, visibility).
- visibility: reasoning visibility: public or private.
HITL terms
- permission.requested / permission.resolved: human-in-the-loop permission flow events.
- permission_id: identifier for the permission request.
- question.requested / question.resolved: human-in-the-loop question flow events.
- question_id: identifier for the question request.
- options: question answer options.
- response: selected answer for a question.
Synthetic terms
- synthetic event: a daemon-emitted event used to fill gaps in provider-native schemas.
- source=daemon: marks synthetic events.
- synthetic delta: a single full-content delta emitted for providers without native deltas.
Provider terms
- agent: the native provider (claude, codex, opencode, amp).
- native payload: the provider’s original event/message object stored in raw.

169
docs/http-api.mdx
View file

@ -1,169 +0,0 @@
---
title: "HTTP API"
description: "Endpoint reference for the sandbox agent daemon."
---
All endpoints are under `/v1`. Authentication uses the daemon-level token via `Authorization: Bearer <token>`.
## Health
<details>
<summary><strong>GET /v1/health</strong> - Connectivity check</summary>
Response:
```json
{ "status": "ok" }
```
</details>
## Sessions
<details>
<summary><strong>POST /v1/sessions/{sessionId}</strong> - Create session</summary>
Request:
```json
{
"agent": "claude",
"agentMode": "build",
"permissionMode": "default",
"model": "claude-3-5-sonnet",
"variant": "high",
"agentVersion": "latest"
}
```
Response:
```json
{
"healthy": true,
"agentSessionId": "..."
}
```
</details>
<details>
<summary><strong>POST /v1/sessions/{sessionId}/messages</strong> - Send message</summary>
Request:
```json
{
"message": "Describe the repository."
}
```
</details>
<details>
<summary><strong>GET /v1/sessions/{sessionId}/events</strong> - Fetch events</summary>
Query params:
- `offset`: last-seen event id (exclusive)
- `limit`: max number of events
Response:
```json
{
"events": [
{
"id": 1,
"timestamp": "2026-01-25T10:00:00Z",
"sessionId": "my-session",
"agent": "claude",
"agentSessionId": "...",
"data": { "message": { "role": "assistant", "parts": [{ "type": "text", "text": "..." }] } }
}
],
"hasMore": false
}
```
</details>
<details>
<summary><strong>GET /v1/sessions/{sessionId}/events/sse</strong> - Stream events (SSE)</summary>
Query params:
- `offset`: last-seen event id (exclusive)
SSE payloads are `UniversalEvent` JSON.
</details>
<details>
<summary><strong>POST /v1/sessions/{sessionId}/questions/{questionId}/reply</strong></summary>
Request:
```json
{ "answers": [["Option A"], ["Option B", "Option C"]] }
```
</details>
<details>
<summary><strong>POST /v1/sessions/{sessionId}/questions/{questionId}/reject</strong></summary>
Request:
```json
{}
```
</details>
<details>
<summary><strong>POST /v1/sessions/{sessionId}/permissions/{permissionId}/reply</strong></summary>
Request:
```json
{ "reply": "once" }
```
</details>
## Agents
<details>
<summary><strong>GET /v1/agents</strong> - List agents</summary>
Response:
```json
{
"agents": [
{ "id": "claude", "installed": true, "version": "...", "path": "/usr/local/bin/claude" }
]
}
```
</details>
<details>
<summary><strong>POST /v1/agents/{agentId}/install</strong> - Install agent</summary>
Request:
```json
{ "reinstall": false }
```
</details>
<details>
<summary><strong>GET /v1/agents/{agentId}/modes</strong> - List modes</summary>
Response:
```json
{
"modes": [
{ "id": "build", "name": "Build", "description": "Default coding mode" }
]
}
```
</details>
## Error handling
All errors use RFC 7807 Problem Details and stable `type` strings (e.g. `urn:sandbox-agent:error:session_not_found`).

BIN
docs/images/inspector.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.1 MiB

68
docs/index.mdx
View file

@ -1,68 +0,0 @@
---
title: "Overview"
description: "Universal API for running Claude Code, Codex, OpenCode, and Amp inside sandboxes."
---
Sandbox Agent SDK is a universal API and daemon for running coding agents inside sandboxes. It standardizes agent sessions, events, and human-in-the-loop workflows across Claude Code, Codex, OpenCode, and Amp.
## At a glance
- Universal HTTP API and TypeScript SDK
- Runs inside sandboxes with a lightweight Rust daemon
- Streams events in a shared UniversalEvent schema
- Supports questions and permission workflows
- Designed for multi-provider sandbox environments
## Quickstart
Run the daemon locally:
```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
Send a message:
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent":"claude"}'
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Explain the repo structure."}'
```
See the full quickstart in [Quickstart](/quickstart).
## What this project solves
- **Universal Coding Agent API**: standardize tool calls, messages, and events across agents.
- **Agents in sandboxes**: run a single HTTP daemon inside any sandbox provider.
- **Agent transcripts**: stream or persist a universal event log in your own storage.
## Project scope
**In scope**
- Agent session orchestration inside a sandbox
- Streaming events in a universal schema
- Human-in-the-loop questions and permissions
- TypeScript SDK and CLI wrappers
**Out of scope**
- Persistent storage of sessions on disk
- Building custom LLM agents (use Vercel AI SDK for that)
- Sandbox provider APIs (use provider SDKs or custom glue)
- Git repo management
## Next steps
- Read the [Architecture](/architecture) overview
- Review [Agent compatibility](/agent-compatibility)
- See the [HTTP API](/http-api) and [CLI](/cli)
- Run the [Frontend demo](/frontend)
- Use the [TypeScript SDK](/typescript-sdk)

45
docs/inspector.mdx Normal file
View file

@ -0,0 +1,45 @@
---
title: "Inspector"
description: "Debug and inspect agent sessions with the Inspector UI."
icon: "magnifying-glass"
---
The Inspector is a web-based GUI for debugging and inspecting Sandbox Agent sessions. Use it to view events, send messages, and troubleshoot agent behavior in real-time.
<Frame>
<img src="/images/inspector.png" alt="Sandbox Agent Inspector" />
</Frame>
## Open the Inspector
Visit [inspect.sandboxagent.dev](https://inspect.sandboxagent.dev) and enter your server URL and token to connect.
You can also generate a pre-filled Inspector URL from the TypeScript SDK:
```typescript
import { buildInspectorUrl } from "sandbox-agent";
const url = buildInspectorUrl({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
});
console.log(url);
// https://inspect.sandboxagent.dev?url=http%3A%2F%2F127.0.0.1%3A2468&token=...
```
## Features
- **Session list**: View all active sessions and their status
- **Event stream**: See events in real-time as they arrive (SSE or polling)
- **Event details**: Expand any event to see its full JSON payload
- **Send messages**: Post messages to a session directly from the UI
- **Agent selection**: Switch between agents and modes
- **Request log**: View raw HTTP requests and responses for debugging
## When to Use
The Inspector is useful for:
- **Development**: Test your integration without writing client code
- **Debugging**: Inspect event payloads and timing issues
- **Learning**: Understand how agents respond to different prompts

264
docs/manage-sessions.mdx
View file

@ -1,21 +1,261 @@
---
title: "Manage Session State"
description: "TODO"
title: "Manage Sessions"
description: "Persist and replay agent transcripts across connections."
icon: "database"
---
TODO
Sandbox Agent stores sessions in memory only. When the server restarts or the sandbox is destroyed, all session data is lost. It's your responsibility to persist events to your own database.
See the [Building a Chat UI](/building-chat-ui) guide for understanding session lifecycle events like `session.started` and `session.ended`.
## Recommended approach
- Store the offset of the last message you have seen (the last event id).
- Update your server to stream events from the Events API using that offset.
- Write the resulting messages and events to your own database.
1. Store events to your database as they arrive
2. On reconnect, get the last event's `sequence` and pass it as `offset`
3. The API returns events where `sequence > offset`
This lets you resume from a known offset after a disconnect and prevents duplicate writes.
This prevents duplicate writes and lets you recover from disconnects.
## Recommended: Rivet Actors
## Receiving Events
If you want a managed way to keep long-running streams alive, consider [Rivet Actors](https://rivet.dev).
They handle continuous event streaming plus fast reads and writes of data for agents, with built-in
realtime support and observability. You can use them to stream `/events/sse` per session and persist
each event to your database as it arrives.
Two ways to receive events: SSE streaming (recommended) or polling.
### Streaming
Use SSE for real-time events with automatic reconnection support.
```typescript
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
});
// Get offset from last stored event (0 returns all events)
const lastEvent = await db.getLastEvent("my-session");
const offset = lastEvent?.sequence ?? 0;
// Stream from where you left off
for await (const event of client.streamEvents("my-session", { offset })) {
await db.insertEvent("my-session", event);
}
```
### Polling
If you can't use SSE streaming, poll the events endpoint:
```typescript
const lastEvent = await db.getLastEvent("my-session");
let offset = lastEvent?.sequence ?? 0;
while (true) {
const { events } = await client.getEvents("my-session", {
offset,
limit: 100
});
for (const event of events) {
await db.insertEvent("my-session", event);
offset = event.sequence;
}
await sleep(1000);
}
```
## Database options
Choose where to persist events based on your requirements. For most use cases, we recommend Rivet Actors.
| | Durable | Real-time | Multiplayer | Scaling | Throughput | Complexity |
|---------|:-------:|:---------:|:-----------:|---------|------------|------------|
| Rivet Actors | ✓ | ✓ | ✓ | Auto-sharded, one actor per session | Millions of concurrent sessions | Zero infrastructure |
| PostgreSQL | ✓ | | | Manual sharding | Connection pool limited | Connection pools, migrations |
| Redis | | ✓ | | Redis Cluster | High, in-memory | Memory management, Sentinel for failover |
### Rivet Actors
For production workloads, [Rivet Actors](https://rivet.gg) provide a managed solution for:
- **Persistent state**: Events survive crashes and restarts
- **Real-time streaming**: Built-in WebSocket support for clients
- **Horizontal scaling**: Run thousands of concurrent sessions
- **Observability**: Built-in logging and metrics
#### Actor
```typescript
import { actor } from "rivetkit";
import { Daytona } from "@daytonaio/sdk";
import { SandboxAgent, SandboxAgentClient, AgentEvent } from "sandbox-agent";
interface CodingSessionState {
sandboxId: string;
baseUrl: string;
sessionId: string;
events: AgentEvent[];
}
interface CodingSessionVars {
client: SandboxAgentClient;
}
const daytona = new Daytona();
const codingSession = actor({
createState: async (): Promise<CodingSessionState> => {
const sandbox = await daytona.create({
snapshot: "sandbox-agent-ready",
envVars: {
ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
OPENAI_API_KEY: process.env.OPENAI_API_KEY,
},
autoStopInterval: 0,
});
await sandbox.process.executeCommand(
"nohup sandbox-agent server --no-token --host 0.0.0.0 --port 3000 &"
);
const baseUrl = (await sandbox.getSignedPreviewUrl(3000)).url;
const sessionId = crypto.randomUUID();
return {
sandboxId: sandbox.id,
baseUrl,
sessionId,
events: [],
};
},
createVars: async (c): Promise<CodingSessionVars> => {
const client = await SandboxAgent.connect({ baseUrl: c.state.baseUrl });
await client.createSession(c.state.sessionId, { agent: "claude" });
return { client };
},
onDestroy: async (c) => {
const sandbox = await daytona.get(c.state.sandboxId);
await sandbox.delete();
},
run: async (c) => {
for await (const event of c.vars.client.streamEvents(c.state.sessionId)) {
c.state.events.push(event);
c.broadcast("agentEvent", event);
}
},
actions: {
postMessage: async (c, message: string) => {
await c.vars.client.postMessage(c.state.sessionId, message);
},
getTranscript: (c) => c.state.events,
},
});
```
#### Client
<CodeGroup>
```typescript TypeScript
import { createClient } from "rivetkit/client";
const client = createClient();
const session = client.codingSession.getOrCreate(["my-session"]);
const conn = session.connect();
conn.on("agentEvent", (event) => {
console.log(event.type, event.data);
});
await conn.postMessage("Create a new React component for user profiles");
const transcript = await conn.getTranscript();
```
```typescript React
import { createRivetKit } from "@rivetkit/react";
const { useActor } = createRivetKit();
function CodingSession() {
const [messages, setMessages] = useState<AgentEvent[]>([]);
const session = useActor({ name: "codingSession", key: ["my-session"] });
session.useEvent("agentEvent", (event) => {
setMessages((prev) => [...prev, event]);
});
const sendPrompt = async (prompt: string) => {
await session.connection?.postMessage(prompt);
};
return (
<div>
{messages.map((msg, i) => (
<div key={i}>{JSON.stringify(msg)}</div>
))}
<button onClick={() => sendPrompt("Build a login page")}>
Send Prompt
</button>
</div>
);
}
```
</CodeGroup>
### PostgreSQL
```sql
CREATE TABLE agent_events (
event_id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
native_session_id TEXT,
sequence INTEGER NOT NULL,
time TIMESTAMPTZ NOT NULL,
type TEXT NOT NULL,
source TEXT NOT NULL,
synthetic BOOLEAN NOT NULL DEFAULT FALSE,
data JSONB NOT NULL,
UNIQUE(session_id, sequence)
);
CREATE INDEX idx_events_session ON agent_events(session_id, sequence);
```
### Redis
```typescript
// Append event to list
await redis.rpush(`session:${sessionId}`, JSON.stringify(event));
// Get events from offset
const events = await redis.lrange(`session:${sessionId}`, offset, -1);
```
## Handling disconnects
The SSE stream may disconnect due to network issues. Handle reconnection gracefully:
```typescript
async function streamWithRetry(sessionId: string) {
while (true) {
try {
const lastEvent = await db.getLastEvent(sessionId);
const offset = lastEvent?.sequence ?? 0;
for await (const event of client.streamEvents(sessionId, { offset })) {
await db.insertEvent(sessionId, event);
}
} catch (error) {
console.error("Stream disconnected, reconnecting...", error);
await sleep(1000);
}
}
}
```

327
docs/quickstart.mdx
View file

@ -1,103 +1,288 @@
---
title: "Quickstart"
description: "Start the server and send your first message."
icon: "rocket"
---
## 1. Run the server
<Steps>
<Step title="Install skill (optional)">
```bash
npx skills add https://sandboxagent.dev/docs
```
</Step>
Use the installed binary, or `cargo run` in development.
<Step title="Set environment variables">
Each coding agent requires API keys to connect to their respective LLM providers.
```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
<Tabs>
<Tab title="Local shell">
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
```
</Tab>
If you want to run without auth (local dev only):
<Tab title="E2B">
```typescript
import { Sandbox } from "@e2b/code-interpreter";
```bash
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
```
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;
If you're running from source instead of the installed CLI:
const sandbox = await Sandbox.create({ envs });
```
</Tab>
```bash
cargo run -p sandbox-agent -- server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
<Tab title="Daytona">
```typescript
import { Daytona } from "@daytonaio/sdk";
### CORS (frontend usage)
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;
If you are calling the server from a browser, enable CORS explicitly:
const daytona = new Daytona();
const sandbox = await daytona.create({
snapshot: "sandbox-agent-ready",
envVars,
});
```
</Tab>
```bash
sandbox-agent server \
--token "$SANDBOX_TOKEN" \
--cors-allow-origin "http://localhost:5173" \
--cors-allow-method "GET" \
--cors-allow-method "POST" \
--cors-allow-header "Authorization" \
--cors-allow-header "Content-Type" \
--cors-allow-credentials
```
<Tab title="Docker">
```bash
docker run -e ANTHROPIC_API_KEY="sk-ant-..." \
-e OPENAI_API_KEY="sk-..." \
your-image
```
</Tab>
</Tabs>
## 2. Install agents (optional)
<AccordionGroup>
<Accordion title="Extracting API keys from current machine">
Use `sandbox-agent credentials extract-env --export` to extract your existing API keys (Anthropic, OpenAI, etc.) from your existing Claude Code or Codex config files on your machine.
</Accordion>
<Accordion title="Testing without API keys">
If you want to test Sandbox Agent without API keys, use the `mock` agent to test the SDK without any credentials. It simulates agent responses for development and testing.
</Accordion>
</AccordionGroup>
</Step>
Agents install lazily on first use. To preinstall everything up front:
<Step title="Run the server">
<Tabs>
<Tab title="curl">
Install and run the binary directly.
```bash
sandbox-agent install-agent claude
sandbox-agent install-agent codex
sandbox-agent install-agent opencode
sandbox-agent install-agent amp
```
```bash
curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
</Tab>
## 3. Create a session
<Tab title="npx">
Run without installing globally.
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent":"claude","agentMode":"build","permissionMode":"default"}'
```
```bash
npx sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
</Tab>
## 4. Send a message
<Tab title="npm i -g">
Install globally, then run.
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Summarize the repository and suggest next steps."}'
```
```bash
npm install -g @sandbox-agent/cli
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
</Tab>
## 5. Read events
<Tab title="Build from source">
If you're running from source instead of the installed CLI.
```bash
curl "http://127.0.0.1:2468/v1/sessions/my-session/events?offset=0&limit=50" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
```bash
cargo run -p sandbox-agent -- server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
```
</Tab>
For streaming output, use SSE:
<Tab title="TypeScript (local)">
For local development, use `SandboxAgent.start()` to automatically spawn and manage the server as a subprocess.
```bash
curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse?offset=0" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
```
```typescript
import { SandboxAgent } from "sandbox-agent";
For a single-turn stream (post a message and get one streamed response):
const client = await SandboxAgent.start();
```
```bash
curl -N -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages/stream" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "content-type: application/json" \
-d '{"message":"Hello"}'
```
This installs the binary and starts the server for you. No manual setup required.
</Tab>
</Tabs>
## 6. CLI shortcuts
<AccordionGroup>
<Accordion title="Running without tokens">
If endpoint is not public, use `--no-token` to disable authentication. Most sandbox providers already secure their networking, so tokens are not required.
</Accordion>
<Accordion title="CORS">
If you're calling the server from a browser, see the [CORS configuration guide](/docs/cors).
</Accordion>
</AccordionGroup>
</Step>
The `sandbox-agent api` subcommand mirrors the HTTP API:
<Step title="Install agents (optional)">
To preinstall agents:
```bash
sandbox-agent api sessions create my-session --agent claude --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
```bash
sandbox-agent install-agent claude
sandbox-agent install-agent codex
sandbox-agent install-agent opencode
sandbox-agent install-agent amp
```
sandbox-agent api sessions send-message my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
If agents are not installed up front, they will be lazily installed when creating a session. It's recommended to pre-install agents then take a snapshot of the sandbox for faster coldstarts.
</Step>
sandbox-agent api sessions send-message-stream my-session --message "Hello" --endpoint http://127.0.0.1:2468 --token "$SANDBOX_TOKEN"
```
<Step title="Create a session">
<Tabs>
<Tab title="TypeScript">
```typescript
import { SandboxAgent } from "sandbox-agent";
const client = await SandboxAgent.connect({
baseUrl: "http://127.0.0.1:2468",
token: process.env.SANDBOX_TOKEN,
});
await client.createSession("my-session", {
agent: "claude",
agentMode: "build",
permissionMode: "default",
});
```
</Tab>
<Tab title="curl">
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent":"claude","agentMode":"build","permissionMode":"default"}'
```
</Tab>
<Tab title="CLI">
```bash
sandbox-agent api sessions create my-session \
--agent claude \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
```
</Tab>
</Tabs>
</Step>
<Step title="Send a message">
<Tabs>
<Tab title="TypeScript">
```typescript
await client.postMessage("my-session", {
message: "Summarize the repository and suggest next steps.",
});
```
</Tab>
<Tab title="curl">
```bash
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Summarize the repository and suggest next steps."}'
```
</Tab>
<Tab title="CLI">
```bash
sandbox-agent api sessions send-message my-session \
--message "Summarize the repository and suggest next steps." \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
```
</Tab>
</Tabs>
</Step>
<Step title="Read events">
<Tabs>
<Tab title="TypeScript">
```typescript
// Poll for events
const events = await client.getEvents("my-session", { offset: 0, limit: 50 });
// Or stream events
for await (const event of client.streamEvents("my-session", { offset: 0 })) {
console.log(event.type, event.data);
}
```
</Tab>
<Tab title="curl">
```bash
# Poll for events
curl "http://127.0.0.1:2468/v1/sessions/my-session/events?offset=0&limit=50" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
# Stream events via SSE
curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse?offset=0" \
-H "Authorization: Bearer $SANDBOX_TOKEN"
# Single-turn stream (post message and get streamed response)
curl -N -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages/stream" \
-H "Authorization: Bearer $SANDBOX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Hello"}'
```
</Tab>
<Tab title="CLI">
```bash
# Poll for events
sandbox-agent api sessions events my-session \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
# Stream events via SSE
sandbox-agent api sessions events-sse my-session \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
# Single-turn stream
sandbox-agent api sessions send-message-stream my-session \
--message "Hello" \
--endpoint http://127.0.0.1:2468 \
--token "$SANDBOX_TOKEN"
```
</Tab>
</Tabs>
</Step>
<Step title="Test with Inspector">
Open the [Inspector UI](https://inspect.sandboxagent.dev) to inspect session state using a GUI.
<Frame>
<img src="/images/inspector.png" alt="Sandbox Agent Inspector" />
</Frame>
</Step>
</Steps>
## Next steps
<CardGroup cols={3}>
<Card title="Build a Chat UI" icon="comments" href="/building-chat-ui">
Learn how to build a chat interface for your agent.
</Card>
<Card title="Manage Sessions" icon="database" href="/manage-sessions">
Persist and replay agent transcripts.
</Card>
<Card title="Deploy to a Sandbox" icon="box" href="/deploy">
Deploy your agent to E2B, Daytona, or Vercel Sandboxes.
</Card>
</CardGroup>

41
docs/sdks/python.mdx Normal file
View file

@ -0,0 +1,41 @@
---
title: "Python"
description: "Python client for managing sessions and streaming events."
icon: "python"
tag: "Coming Soon"
---
The Python SDK is on our roadmap. It will provide a typed client for managing sessions and streaming events, similar to the TypeScript SDK.
In the meantime, you can use the [HTTP API](/http-api) directly with any HTTP client like `requests` or `httpx`.
```python
import httpx
base_url = "http://127.0.0.1:2468"
headers = {"Authorization": f"Bearer {token}"}
# Create a session
httpx.post(
f"{base_url}/v1/sessions/my-session",
headers=headers,
json={"agent": "claude", "permissionMode": "default"}
)
# Send a message
httpx.post(
f"{base_url}/v1/sessions/my-session/messages",
headers=headers,
json={"message": "Hello from Python"}
)
# Get events
response = httpx.get(
f"{base_url}/v1/sessions/my-session/events",
headers=headers,
params={"offset": 0, "limit": 50}
)
events = response.json()["events"]
```
Want the Python SDK sooner? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues) to let us know.

5
docs/sdks/typescript.mdx
View file

@ -1,6 +1,7 @@
---
title: "TypeScript SDK"
title: "TypeScript"
description: "Use the generated client to manage sessions and stream events."
icon: "js"
---
The TypeScript SDK is generated from the OpenAPI spec that ships with the server. It provides a typed
@ -147,4 +148,4 @@ The SDK exports OpenAPI-derived types for events, items, and capabilities:
import type { UniversalEvent, UniversalItem, AgentCapabilities } from "sandbox-agent";
```
See `docs/universal-api.mdx` for the universal schema fields and semantics.
See the [API Reference](/api) for schema details.

5
docs/telemetry.mdx
View file

@ -24,8 +24,3 @@ Disable it with:
sandbox-agent server --no-telemetry
```
Debug builds disable telemetry automatically. You can opt in with:
```bash
SANDBOX_AGENT_TELEMETRY_DEBUG=1 sandbox-agent server
```

9
docs/theme.css
View file

@ -20,6 +20,7 @@ body {
color: var(--sa-text);
}
/*
a {
color: var(--sa-primary);
}
@ -40,13 +41,6 @@ select {
color: var(--sa-text);
}
code,
pre {
background-color: var(--sa-card);
border: 1px solid var(--sa-border);
color: var(--sa-text);
}
.card,
.mintlify-card,
.docs-card {
@ -70,3 +64,4 @@ pre {
.alert-danger {
border-color: var(--sa-danger);
}
*/

30
docs/universal-api.mdx
View file

@ -1,30 +0,0 @@
---
title: "Universal API"
description: "Feature checklist and normalization rules."
---
## Feature checklist
- [x] Session creation and lifecycle events
- [x] Message streaming (assistant and tool messages)
- [x] Tool call and tool result normalization
- [x] File and image parts
- [x] Human-in-the-loop questions
- [x] Permission prompts and replies
- [x] Plan approval normalization (Claude -> question)
- [x] Event streaming over SSE
- [ ] Persistent storage (out of scope)
## Normalization rules
- **Session ID** is always the client-provided ID.
- **Agent session ID** is surfaced in events but never replaces the primary session ID.
- **Tool calls** map to `UniversalMessagePart::ToolCall` and results to `ToolResult`.
- **File and image parts** map to `AttachmentSource` with `Path`, `Url`, or base64 `Data`.
## Agent mode vs permission mode
- **agentMode**: behavior or system prompt strategy (build/plan/custom).
- **permissionMode**: capability restrictions (default/plan/bypass).
These are separate concepts and must be configured independently.

291
docs/universal-schema.mdx Normal file
View file

@ -0,0 +1,291 @@
---
title: "Universal Schema"
description: "Reference for the universal event and item schema."
icon: "brackets-curly"
---
The universal schema normalizes events from all supported agents (Claude Code, Codex, OpenCode, Amp) into a consistent format. This lets you build UIs and persistence layers that work with any agent without special-casing.
The schema is defined in [OpenAPI format](https://github.com/rivet-dev/sandbox-agent/blob/main/docs/openapi.json). See the [HTTP API Reference](/api-reference) for endpoint documentation.
## UniversalEvent
Every event from the API is wrapped in a `UniversalEvent` envelope.
| Field | Type | Description |
|-------|------|-------------|
| `event_id` | string | Unique identifier for this event |
| `sequence` | integer | Monotonic sequence number within the session (starts at 1) |
| `time` | string | RFC3339 timestamp |
| `session_id` | string | Daemon-generated session identifier |
| `native_session_id` | string? | Provider-native session/thread identifier (e.g., Codex `threadId`, OpenCode `sessionID`) |
| `source` | string | Event origin: `agent` (native) or `daemon` (synthetic) |
| `synthetic` | boolean | Whether this event was generated by the daemon to fill gaps |
| `type` | string | Event type (see [Event Types](#event-types)) |
| `data` | object | Event-specific payload |
| `raw` | any? | Original provider payload (only when `include_raw=true`) |
```json
{
"event_id": "evt_abc123",
"sequence": 1,
"time": "2025-01-28T12:00:00Z",
"session_id": "my-session",
"native_session_id": "thread_xyz",
"source": "agent",
"synthetic": false,
"type": "item.completed",
"data": { ... }
}
```
## Event Types
### Session Lifecycle
| Type | Description | Data |
|------|-------------|------|
| `session.started` | Session has started | `{ metadata?: any }` |
| `session.ended` | Session has ended | `{ reason, terminated_by }` |
**SessionEndedData**
| Field | Type | Values |
|-------|------|--------|
| `reason` | string | `completed`, `error`, `terminated` |
| `terminated_by` | string | `agent`, `daemon` |
### Item Lifecycle
| Type | Description | Data |
|------|-------------|------|
| `item.started` | Item creation | `{ item }` |
| `item.delta` | Streaming content delta | `{ item_id, native_item_id?, delta }` |
| `item.completed` | Item finalized | `{ item }` |
Items follow a consistent lifecycle: `item.started` → `item.delta` (0 or more) → `item.completed`.
### HITL (Human-in-the-Loop)
| Type | Description | Data |
|------|-------------|------|
| `permission.requested` | Permission request pending | `{ permission_id, action, status, metadata? }` |
| `permission.resolved` | Permission granted or denied | `{ permission_id, action, status, metadata? }` |
| `question.requested` | Question pending user input | `{ question_id, prompt, options, status }` |
| `question.resolved` | Question answered or rejected | `{ question_id, prompt, options, status, response? }` |
**PermissionEventData**
| Field | Type | Description |
|-------|------|-------------|
| `permission_id` | string | Identifier for the permission request |
| `action` | string | What the agent wants to do |
| `status` | string | `requested`, `approved`, `denied` |
| `metadata` | any? | Additional context |
**QuestionEventData**
| Field | Type | Description |
|-------|------|-------------|
| `question_id` | string | Identifier for the question |
| `prompt` | string | Question text |
| `options` | string[] | Available answer options |
| `status` | string | `requested`, `answered`, `rejected` |
| `response` | string? | Selected answer (when resolved) |
### Errors
| Type | Description | Data |
|------|-------------|------|
| `error` | Runtime error | `{ message, code?, details? }` |
| `agent.unparsed` | Parse failure | `{ error, location, raw_hash? }` |
The `agent.unparsed` event indicates the daemon failed to parse an agent payload. This should be treated as a bug.
## UniversalItem
Items represent discrete units of content within a session.
| Field | Type | Description |
|-------|------|-------------|
| `item_id` | string | Daemon-generated identifier |
| `native_item_id` | string? | Provider-native item/message identifier |
| `parent_id` | string? | Parent item ID (e.g., tool call/result parented to a message) |
| `kind` | string | Item category (see below) |
| `role` | string? | Actor role for message items |
| `status` | string | Lifecycle status |
| `content` | ContentPart[] | Ordered list of content parts |
### ItemKind
| Value | Description |
|-------|-------------|
| `message` | User or assistant message |
| `tool_call` | Tool invocation |
| `tool_result` | Tool execution result |
| `system` | System message |
| `status` | Status update |
| `unknown` | Unrecognized item type |
### ItemRole
| Value | Description |
|-------|-------------|
| `user` | User message |
| `assistant` | Assistant response |
| `system` | System prompt |
| `tool` | Tool-related message |
### ItemStatus
| Value | Description |
|-------|-------------|
| `in_progress` | Item is streaming or pending |
| `completed` | Item is finalized |
| `failed` | Item execution failed |
## Content Parts
The `content` array contains typed parts that make up an item's payload.
### text
Plain text content.
```json
{ "type": "text", "text": "Hello, world!" }
```
### json
Structured JSON content.
```json
{ "type": "json", "json": { "key": "value" } }
```
### tool_call
Tool invocation.
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Tool name |
| `arguments` | string | JSON-encoded arguments |
| `call_id` | string | Unique call identifier |
```json
{
"type": "tool_call",
"name": "read_file",
"arguments": "{\"path\": \"/src/main.ts\"}",
"call_id": "call_abc123"
}
```
### tool_result
Tool execution result.
| Field | Type | Description |
|-------|------|-------------|
| `call_id` | string | Matching call identifier |
| `output` | string | Tool output |
```json
{
"type": "tool_result",
"call_id": "call_abc123",
"output": "File contents here..."
}
```
### file_ref
File reference with optional diff.
| Field | Type | Description |
|-------|------|-------------|
| `path` | string | File path |
| `action` | string | `read`, `write`, `patch` |
| `diff` | string? | Unified diff (for patches) |
```json
{
"type": "file_ref",
"path": "/src/main.ts",
"action": "write",
"diff": "@@ -1,3 +1,4 @@\n+import { foo } from 'bar';"
}
```
### image
Image reference.
| Field | Type | Description |
|-------|------|-------------|
| `path` | string | Image file path |
| `mime` | string? | MIME type |
```json
{ "type": "image", "path": "/tmp/screenshot.png", "mime": "image/png" }
```
### reasoning
Model reasoning/thinking content.
| Field | Type | Description |
|-------|------|-------------|
| `text` | string | Reasoning text |
| `visibility` | string | `public` or `private` |
```json
{ "type": "reasoning", "text": "Let me think about this...", "visibility": "public" }
```
### status
Status indicator.
| Field | Type | Description |
|-------|------|-------------|
| `label` | string | Status label |
| `detail` | string? | Additional detail |
```json
{ "type": "status", "label": "Running tests", "detail": "3 of 10 passed" }
```
## Source & Synthetics
### EventSource
The `source` field indicates who emitted the event:
| Value | Description |
|-------|-------------|
| `agent` | Native event from the agent |
| `daemon` | Synthetic event generated by the daemon |
### Synthetic Events
The daemon emits synthetic events (`synthetic: true`, `source: "daemon"`) to provide a consistent event stream across all agents. Common synthetics:
| Synthetic | When |
|-----------|------|
| `session.started` | Agent doesn't emit explicit session start |
| `session.ended` | Agent doesn't emit explicit session end |
| `item.started` | Agent doesn't emit item start events |
| `item.delta` | Agent doesn't stream deltas natively |
| `question.*` | Claude Code plan mode (from ExitPlanMode tool) |
### Raw Payloads
Pass `include_raw=true` to event endpoints to receive the original agent payload in the `raw` field. Useful for debugging or accessing agent-specific data not in the universal schema.
```typescript
const events = await client.getEvents("my-session", { includeRaw: true });
// events[0].raw contains the original agent payload
```

2
frontend/packages/inspector/src/components/ConnectScreen.tsx
View file

@ -102,7 +102,7 @@ const ConnectScreen = ({
<p className="hint">
Start the server with CORS enabled for browser access:
<br />
<code>sandbox-agent server --cors-allow-origin http://localhost:5173</code>
<code>sandbox-agent server --cors-allow-origin {window.location.origin}</code>
</p>
</div>
</div>

1
frontend/packages/website/.astro/content-assets.mjs
View file

@ -1 +0,0 @@
export default new Map();

1
frontend/packages/website/.astro/content-modules.mjs
View file

@ -1 +0,0 @@
export default new Map();

199
frontend/packages/website/.astro/content.d.ts vendored
View file

@ -1,199 +0,0 @@
declare module 'astro:content' {
export interface RenderResult {
Content: import('astro/runtime/server/index.js').AstroComponentFactory;
headings: import('astro').MarkdownHeading[];
remarkPluginFrontmatter: Record<string, any>;
}
interface Render {
'.md': Promise<RenderResult>;
}
export interface RenderedContent {
html: string;
metadata?: {
imagePaths: Array<string>;
[key: string]: unknown;
};
}
}
declare module 'astro:content' {
type Flatten<T> = T extends { [K: string]: infer U } ? U : never;
export type CollectionKey = keyof AnyEntryMap;
export type CollectionEntry<C extends CollectionKey> = Flatten<AnyEntryMap[C]>;
export type ContentCollectionKey = keyof ContentEntryMap;
export type DataCollectionKey = keyof DataEntryMap;
type AllValuesOf<T> = T extends any ? T[keyof T] : never;
type ValidContentEntrySlug<C extends keyof ContentEntryMap> = AllValuesOf<
ContentEntryMap[C]
>['slug'];
export type ReferenceDataEntry<
C extends CollectionKey,
E extends keyof DataEntryMap[C] = string,
> = {
collection: C;
id: E;
};
export type ReferenceContentEntry<
C extends keyof ContentEntryMap,
E extends ValidContentEntrySlug<C> | (string & {}) = string,
> = {
collection: C;
slug: E;
};
export type ReferenceLiveEntry<C extends keyof LiveContentConfig['collections']> = {
collection: C;
id: string;
};
/** @deprecated Use `getEntry` instead. */
export function getEntryBySlug<
C extends keyof ContentEntryMap,
E extends ValidContentEntrySlug<C> | (string & {}),
>(
collection: C,
// Note that this has to accept a regular string too, for SSR
entrySlug: E,
): E extends ValidContentEntrySlug<C>
? Promise<CollectionEntry<C>>
: Promise<CollectionEntry<C> | undefined>;
/** @deprecated Use `getEntry` instead. */
export function getDataEntryById<C extends keyof DataEntryMap, E extends keyof DataEntryMap[C]>(
collection: C,
entryId: E,
): Promise<CollectionEntry<C>>;
export function getCollection<C extends keyof AnyEntryMap, E extends CollectionEntry<C>>(
collection: C,
filter?: (entry: CollectionEntry<C>) => entry is E,
): Promise<E[]>;
export function getCollection<C extends keyof AnyEntryMap>(
collection: C,
filter?: (entry: CollectionEntry<C>) => unknown,
): Promise<CollectionEntry<C>[]>;
export function getLiveCollection<C extends keyof LiveContentConfig['collections']>(
collection: C,
filter?: LiveLoaderCollectionFilterType<C>,
): Promise<
import('astro').LiveDataCollectionResult<LiveLoaderDataType<C>, LiveLoaderErrorType<C>>
>;
export function getEntry<
C extends keyof ContentEntryMap,
E extends ValidContentEntrySlug<C> | (string & {}),
>(
entry: ReferenceContentEntry<C, E>,
): E extends ValidContentEntrySlug<C>
? Promise<CollectionEntry<C>>
: Promise<CollectionEntry<C> | undefined>;
export function getEntry<
C extends keyof DataEntryMap,
E extends keyof DataEntryMap[C] | (string & {}),
>(
entry: ReferenceDataEntry<C, E>,
): E extends keyof DataEntryMap[C]
? Promise<DataEntryMap[C][E]>
: Promise<CollectionEntry<C> | undefined>;
export function getEntry<
C extends keyof ContentEntryMap,
E extends ValidContentEntrySlug<C> | (string & {}),
>(
collection: C,
slug: E,
): E extends ValidContentEntrySlug<C>
? Promise<CollectionEntry<C>>
: Promise<CollectionEntry<C> | undefined>;
export function getEntry<
C extends keyof DataEntryMap,
E extends keyof DataEntryMap[C] | (string & {}),
>(
collection: C,
id: E,
): E extends keyof DataEntryMap[C]
? string extends keyof DataEntryMap[C]
? Promise<DataEntryMap[C][E]> | undefined
: Promise<DataEntryMap[C][E]>
: Promise<CollectionEntry<C> | undefined>;
export function getLiveEntry<C extends keyof LiveContentConfig['collections']>(
collection: C,
filter: string | LiveLoaderEntryFilterType<C>,
): Promise<import('astro').LiveDataEntryResult<LiveLoaderDataType<C>, LiveLoaderErrorType<C>>>;
/** Resolve an array of entry references from the same collection */
export function getEntries<C extends keyof ContentEntryMap>(
entries: ReferenceContentEntry<C, ValidContentEntrySlug<C>>[],
): Promise<CollectionEntry<C>[]>;
export function getEntries<C extends keyof DataEntryMap>(
entries: ReferenceDataEntry<C, keyof DataEntryMap[C]>[],
): Promise<CollectionEntry<C>[]>;
export function render<C extends keyof AnyEntryMap>(
entry: AnyEntryMap[C][string],
): Promise<RenderResult>;
export function reference<C extends keyof AnyEntryMap>(
collection: C,
): import('astro/zod').ZodEffects<
import('astro/zod').ZodString,
C extends keyof ContentEntryMap
? ReferenceContentEntry<C, ValidContentEntrySlug<C>>
: ReferenceDataEntry<C, keyof DataEntryMap[C]>
>;
// Allow generic `string` to avoid excessive type errors in the config
// if `dev` is not running to update as you edit.
// Invalid collection names will be caught at build time.
export function reference<C extends string>(
collection: C,
): import('astro/zod').ZodEffects<import('astro/zod').ZodString, never>;
type ReturnTypeOrOriginal<T> = T extends (...args: any[]) => infer R ? R : T;
type InferEntrySchema<C extends keyof AnyEntryMap> = import('astro/zod').infer<
ReturnTypeOrOriginal<Required<ContentConfig['collections'][C]>['schema']>
>;
type ContentEntryMap = {
};
type DataEntryMap = {
};
type AnyEntryMap = ContentEntryMap & DataEntryMap;
type ExtractLoaderTypes<T> = T extends import('astro/loaders').LiveLoader<
infer TData,
infer TEntryFilter,
infer TCollectionFilter,
infer TError
>
? { data: TData; entryFilter: TEntryFilter; collectionFilter: TCollectionFilter; error: TError }
: { data: never; entryFilter: never; collectionFilter: never; error: never };
type ExtractDataType<T> = ExtractLoaderTypes<T>['data'];
type ExtractEntryFilterType<T> = ExtractLoaderTypes<T>['entryFilter'];
type ExtractCollectionFilterType<T> = ExtractLoaderTypes<T>['collectionFilter'];
type ExtractErrorType<T> = ExtractLoaderTypes<T>['error'];
type LiveLoaderDataType<C extends keyof LiveContentConfig['collections']> =
LiveContentConfig['collections'][C]['schema'] extends undefined
? ExtractDataType<LiveContentConfig['collections'][C]['loader']>
: import('astro/zod').infer<
Exclude<LiveContentConfig['collections'][C]['schema'], undefined>
>;
type LiveLoaderEntryFilterType<C extends keyof LiveContentConfig['collections']> =
ExtractEntryFilterType<LiveContentConfig['collections'][C]['loader']>;
type LiveLoaderCollectionFilterType<C extends keyof LiveContentConfig['collections']> =
ExtractCollectionFilterType<LiveContentConfig['collections'][C]['loader']>;
type LiveLoaderErrorType<C extends keyof LiveContentConfig['collections']> = ExtractErrorType<
LiveContentConfig['collections'][C]['loader']
>;
export type ContentConfig = typeof import("../src/content.config.mjs");
export type LiveContentConfig = never;
}

1
frontend/packages/website/.astro/data-store.json
View file

@ -1 +0,0 @@
[["Map",1,2],"meta::meta",["Map",3,4,5,6],"astro-version","5.16.15","astro-config-digest","{\"root\":{},\"srcDir\":{},\"publicDir\":{},\"outDir\":{},\"cacheDir\":{},\"compressHTML\":true,\"base\":\"/\",\"trailingSlash\":\"ignore\",\"output\":\"static\",\"scopedStyleStrategy\":\"attribute\",\"build\":{\"format\":\"directory\",\"client\":{},\"server\":{},\"assets\":\"_astro\",\"serverEntry\":\"entry.mjs\",\"redirects\":true,\"inlineStylesheets\":\"auto\",\"concurrency\":1},\"server\":{\"open\":false,\"host\":false,\"port\":4321,\"streaming\":true,\"allowedHosts\":[]},\"redirects\":{},\"image\":{\"endpoint\":{\"route\":\"/_image\"},\"service\":{\"entrypoint\":\"astro/assets/services/sharp\",\"config\":{}},\"domains\":[],\"remotePatterns\":[],\"responsiveStyles\":false},\"devToolbar\":{\"enabled\":true},\"markdown\":{\"syntaxHighlight\":{\"type\":\"shiki\",\"excludeLangs\":[\"math\"]},\"shikiConfig\":{\"langs\":[],\"langAlias\":{},\"theme\":\"github-dark\",\"themes\":{},\"wrap\":false,\"transformers\":[]},\"remarkPlugins\":[],\"rehypePlugins\":[],\"remarkRehype\":{},\"gfm\":true,\"smartypants\":true},\"security\":{\"checkOrigin\":true,\"allowedDomains\":[]},\"env\":{\"schema\":{},\"validateSecrets\":false},\"experimental\":{\"clientPrerender\":false,\"contentIntellisense\":false,\"headingIdCompat\":false,\"preserveScriptOrder\":false,\"liveContentCollections\":false,\"csp\":false,\"staticImportMetaEnv\":false,\"chromeDevtoolsWorkspace\":false,\"failOnPrerenderConflict\":false,\"svgo\":false},\"legacy\":{\"collections\":false}}"]

5
frontend/packages/website/.astro/settings.json
View file

@ -1,5 +0,0 @@
{
"_variables": {
"lastUpdateCheck": 1769576078224
}
}

1
frontend/packages/website/.astro/types.d.ts vendored
View file

@ -1 +0,0 @@
/// <reference types="astro/client" />

3
frontend/packages/website/.gitignore vendored Normal file
View file

@ -0,0 +1,3 @@
.astro
dist
node_modules

2
sdks/typescript/package.json
View file

@ -20,7 +20,7 @@
"dist"
],
"scripts": {
"generate:openapi": "cargo check -p sandbox-agent-openapi-gen && cargo run -p sandbox-agent-openapi-gen -- --out ../../docs/openapi.json",
"generate:openapi": "SANDBOX_AGENT_SKIP_INSPECTOR=1 cargo run -p sandbox-agent-openapi-gen -- --out ../../docs/openapi.json",
"generate:types": "openapi-typescript ../../docs/openapi.json -o src/generated/openapi.ts",
"generate": "pnpm run generate:openapi && pnpm run generate:types",
"build": "if [ -z \"$SKIP_OPENAPI_GEN\" ]; then pnpm run generate:openapi; fi && pnpm run generate:types && tsup",

35
docs/architecture.mdx → server/ARCHITECTURE.md
View file

@ -1,7 +1,6 @@
---
title: "Architecture"
description: "How the daemon, schemas, and agents fit together."
---
# Architecture
How the daemon, schemas, and agents fit together.
Sandbox Agent SDK is built around a single daemon that runs inside the sandbox and exposes a universal HTTP API. Clients use the API (or the TypeScript SDK / CLI) to create sessions, send messages, and stream events.
@ -348,3 +347,31 @@ The daemon uses a **global token** configured at startup. All HTTP and CLI opera
| Event converters | `server/packages/universal-agent-schema/src/agents/*.rs` |
| Schema extractors | `resources/agent-schemas/src/*.ts` |
| TypeScript SDK | `sdks/typescript/src/` |
---
# Agent Compatibility
Supported agents, install methods, and streaming formats.
## Compatibility Matrix
| Agent | Provider | Binary | Install method | Session ID | Streaming format |
|-------|----------|--------|----------------|------------|------------------|
| Claude Code | Anthropic | `claude` | curl raw binary from GCS | `session_id` | JSONL via stdout |
| Codex | OpenAI | `codex` | curl tarball from GitHub releases | `thread_id` | JSON-RPC over stdio |
| OpenCode | Multi-provider | `opencode` | curl tarball from GitHub releases | `session_id` | SSE or JSONL |
| Amp | Sourcegraph | `amp` | curl raw binary from GCS | `session_id` | JSONL via stdout |
| Mock | Built-in | — | bundled | `mock-*` | daemon-generated |
## Agent Modes
- **OpenCode**: discovered via the server API.
- **Claude Code / Codex / Amp**: hardcoded modes (typically `build`, `plan`, or `custom`).
## Capability Notes
- **Questions / permissions**: OpenCode natively supports these workflows. Claude plan approval is normalized into a question event (tests do not currently exercise Claude question/permission flows).
- **Streaming**: all agents stream events; OpenCode uses SSE, Codex uses JSON-RPC over stdio, others use JSONL. Codex is currently normalized to thread/turn starts plus user/assistant completed items (deltas and tool/reasoning items are not emitted yet).
- **User messages**: Claude CLI output does not include explicit user-message events in our snapshots, so only assistant messages are surfaced for Claude today.
- **Files and images**: normalized via `UniversalMessagePart` with `File` and `Image` parts.

4
server/CLAUDE.md
View file

@ -1,3 +1,7 @@
# Server
See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed architecture documentation covering the daemon, agent schema pipeline, session management, agent execution patterns, and SDK modes.
# Server Testing
## Test placement