mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 14:03:52 +00:00
chore: recover wellington workspace state
This commit is contained in:
Nathan Flurry
parent
5d65013aa5
commit
c294ca85be
366 changed files with 1265 additions and 53395 deletions
|
|
@ -1,127 +0,0 @@
|
|||
---
|
||||
title: "Agent Capabilities"
|
||||
description: "Models, modes, and thought levels supported by each agent."
|
||||
---
|
||||
|
||||
Capabilities are subject to change as the agents are updated. See [Agent Sessions](/agent-sessions) for full session configuration API details.
|
||||
|
||||
|
||||
<Info>
|
||||
_Last updated: March 5th, 2026. See [Generating a live report](#generating-a-live-report) for up-to-date reference._
|
||||
</Info>
|
||||
|
||||
## Claude
|
||||
|
||||
| Category | Values |
|
||||
|----------|--------|
|
||||
| **Models** | `default`, `sonnet`, `opus`, `haiku` |
|
||||
| **Modes** | `default`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions` |
|
||||
| **Thought levels** | Unsupported |
|
||||
|
||||
### Configuring Effort Level For Claude
|
||||
|
||||
Claude does not natively support changing effort level after a session starts, so configure it in the filesystem before creating the session.
|
||||
|
||||
```ts
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
|
||||
const cwd = "/path/to/workspace";
|
||||
await mkdir(path.join(cwd, ".claude"), { recursive: true });
|
||||
await writeFile(
|
||||
path.join(cwd, ".claude", "settings.json"),
|
||||
JSON.stringify({ effortLevel: "high" }, null, 2),
|
||||
);
|
||||
|
||||
const sdk = await SandboxAgent.connect({ baseUrl: "http://127.0.0.1:2468" });
|
||||
await sdk.createSession({
|
||||
agent: "claude",
|
||||
sessionInit: { cwd, mcpServers: [] },
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="Supported file locations (highest precedence last)">
|
||||
|
||||
1. `~/.claude/settings.json`
|
||||
2. `<session cwd>/.claude/settings.json`
|
||||
3. `<session cwd>/.claude/settings.local.json`
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Codex
|
||||
|
||||
| Category | Values |
|
||||
|----------|--------|
|
||||
| **Models** | `gpt-5.3-codex` (default), `gpt-5.3-codex-spark`, `gpt-5.2-codex`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1-codex-mini` |
|
||||
| **Modes** | `read-only` (default), `auto`, `full-access` |
|
||||
| **Thought levels** | `low`, `medium`, `high` (default), `xhigh` |
|
||||
|
||||
## OpenCode
|
||||
|
||||
| Category | Values |
|
||||
|----------|--------|
|
||||
| **Models** | See below |
|
||||
| **Modes** | `build` (default), `plan` |
|
||||
| **Thought levels** | Unsupported |
|
||||
|
||||
<Accordion title="See all models">
|
||||
|
||||
| Provider | Models |
|
||||
|----------|--------|
|
||||
| **Anthropic** | `anthropic/claude-3-5-haiku-20241022`, `anthropic/claude-3-5-haiku-latest`, `anthropic/claude-3-5-sonnet-20240620`, `anthropic/claude-3-5-sonnet-20241022`, `anthropic/claude-3-7-sonnet-20250219`, `anthropic/claude-3-7-sonnet-latest`, `anthropic/claude-3-haiku-20240307`, `anthropic/claude-3-opus-20240229`, `anthropic/claude-3-sonnet-20240229`, `anthropic/claude-haiku-4-5`, `anthropic/claude-haiku-4-5-20251001`, `anthropic/claude-opus-4-0`, `anthropic/claude-opus-4-1`, `anthropic/claude-opus-4-1-20250805`, `anthropic/claude-opus-4-20250514`, `anthropic/claude-opus-4-5`, `anthropic/claude-opus-4-5-20251101`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-0`, `anthropic/claude-sonnet-4-20250514`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-sonnet-4-5-20250929` |
|
||||
| **OpenAI** | `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.3-codex` |
|
||||
| **Cerebras** | `cerebras/gpt-oss-120b`, `cerebras/qwen-3-235b-a22b-instruct-2507`, `cerebras/zai-glm-4.7` |
|
||||
| **OpenCode Zen** | `opencode/big-pickle`, `opencode/claude-3-5-haiku`, `opencode/claude-haiku-4-5`, `opencode/claude-opus-4-1`, `opencode/claude-opus-4-5`, `opencode/claude-opus-4-6`, `opencode/claude-sonnet-4`, `opencode/claude-sonnet-4-5`, `opencode/gemini-3-flash`, `opencode/gemini-3-pro` (default), `opencode/glm-4.6`, `opencode/glm-4.7`, `opencode/gpt-5`, `opencode/gpt-5-codex`, `opencode/gpt-5-nano`, `opencode/gpt-5.1`, `opencode/gpt-5.1-codex`, `opencode/gpt-5.1-codex-max`, `opencode/gpt-5.1-codex-mini`, `opencode/gpt-5.2`, `opencode/gpt-5.2-codex`, `opencode/kimi-k2`, `opencode/kimi-k2-thinking`, `opencode/kimi-k2.5`, `opencode/kimi-k2.5-free`, `opencode/minimax-m2.1`, `opencode/minimax-m2.1-free`, `opencode/trinity-large-preview-free` |
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Cursor
|
||||
|
||||
| Category | Values |
|
||||
|----------|--------|
|
||||
| **Models** | See below |
|
||||
| **Modes** | Unsupported |
|
||||
| **Thought levels** | Unsupported |
|
||||
|
||||
<Accordion title="See all models">
|
||||
|
||||
| Group | Models |
|
||||
|-------|--------|
|
||||
| **Auto** | `auto` |
|
||||
| **Composer** | `composer-1.5`, `composer-1` |
|
||||
| **GPT-5.3 Codex** | `gpt-5.3-codex`, `gpt-5.3-codex-low`, `gpt-5.3-codex-high`, `gpt-5.3-codex-xhigh`, `gpt-5.3-codex-fast`, `gpt-5.3-codex-low-fast`, `gpt-5.3-codex-high-fast`, `gpt-5.3-codex-xhigh-fast` |
|
||||
| **GPT-5.2** | `gpt-5.2`, `gpt-5.2-high`, `gpt-5.2-codex`, `gpt-5.2-codex-low`, `gpt-5.2-codex-high`, `gpt-5.2-codex-xhigh`, `gpt-5.2-codex-fast`, `gpt-5.2-codex-low-fast`, `gpt-5.2-codex-high-fast`, `gpt-5.2-codex-xhigh-fast` |
|
||||
| **GPT-5.1** | `gpt-5.1-high`, `gpt-5.1-codex-max`, `gpt-5.1-codex-max-high` |
|
||||
| **Claude** | `opus-4.6-thinking` (default), `opus-4.6`, `opus-4.5`, `opus-4.5-thinking`, `sonnet-4.5`, `sonnet-4.5-thinking` |
|
||||
| **Other** | `gemini-3-pro`, `gemini-3-flash`, `grok` |
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Amp
|
||||
|
||||
| Category | Values |
|
||||
|----------|--------|
|
||||
| **Models** | `amp-default` |
|
||||
| **Modes** | `default`, `bypass` |
|
||||
| **Thought levels** | Unsupported |
|
||||
|
||||
## Pi
|
||||
|
||||
| Category | Values |
|
||||
|----------|--------|
|
||||
| **Models** | `default` |
|
||||
| **Modes** | Unsupported |
|
||||
| **Thought levels** | Unsupported |
|
||||
|
||||
## Generating a live report
|
||||
|
||||
Requires a running Sandbox Agent server. `--endpoint` defaults to `http://127.0.0.1:2468`.
|
||||
|
||||
```bash
|
||||
sandbox-agent api agents report
|
||||
```
|
||||
|
||||
<Note>
|
||||
The live report reflects what the agent adapter returns for the current credentials. Some models may be gated by subscription (e.g. Claude's `opus` requires a paid plan) and will not appear in the report if the credentials don't have access.
|
||||
</Note>
|
||||
|
|
@ -82,49 +82,6 @@ if (sessions.items.length > 0) {
|
|||
}
|
||||
```
|
||||
|
||||
## Configure model, mode, and thought level
|
||||
|
||||
Set the model, mode, or thought level on a session at creation time or after:
|
||||
|
||||
```ts
|
||||
// At creation time
|
||||
const session = await sdk.createSession({
|
||||
agent: "codex",
|
||||
model: "gpt-5.3-codex",
|
||||
mode: "auto",
|
||||
thoughtLevel: "high",
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// After creation
|
||||
await session.setModel("gpt-5.2-codex");
|
||||
await session.setMode("full-access");
|
||||
await session.setThoughtLevel("medium");
|
||||
```
|
||||
|
||||
Query available modes:
|
||||
|
||||
```ts
|
||||
const modes = await session.getModes();
|
||||
console.log(modes?.currentModeId, modes?.availableModes);
|
||||
```
|
||||
|
||||
### Advanced config options
|
||||
|
||||
For config options beyond model, mode, and thought level, use `getConfigOptions` to discover what the agent supports and `setConfigOption` to set any option by ID:
|
||||
|
||||
```ts
|
||||
const options = await session.getConfigOptions();
|
||||
for (const opt of options) {
|
||||
console.log(opt.id, opt.category, opt.type);
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
await session.setConfigOption("some-agent-option", "value");
|
||||
```
|
||||
|
||||
## Destroy a session
|
||||
|
||||
```ts
|
||||
|
|
|
|||
59
docs/cli.mdx
59
docs/cli.mdx
|
|
@ -167,65 +167,6 @@ Shared option:
|
|||
|
||||
```bash
|
||||
sandbox-agent api agents list [--endpoint <URL>]
|
||||
sandbox-agent api agents report [--endpoint <URL>]
|
||||
sandbox-agent api agents install <AGENT> [--reinstall] [--endpoint <URL>]
|
||||
```
|
||||
|
||||
#### api agents list
|
||||
|
||||
List all agents and their install status.
|
||||
|
||||
```bash
|
||||
sandbox-agent api agents list
|
||||
```
|
||||
|
||||
#### api agents report
|
||||
|
||||
Emit a JSON report of available models, modes, and thought levels for every agent. Calls `GET /v1/agents?config=true` and groups each agent's config options by category.
|
||||
|
||||
```bash
|
||||
sandbox-agent api agents report --endpoint http://127.0.0.1:2468 | jq .
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```json
|
||||
{
|
||||
"generatedAtMs": 1740000000000,
|
||||
"endpoint": "http://127.0.0.1:2468",
|
||||
"agents": [
|
||||
{
|
||||
"id": "claude",
|
||||
"installed": true,
|
||||
"models": {
|
||||
"currentValue": "default",
|
||||
"values": [
|
||||
{ "value": "default", "name": "Default" },
|
||||
{ "value": "sonnet", "name": "Sonnet" },
|
||||
{ "value": "opus", "name": "Opus" },
|
||||
{ "value": "haiku", "name": "Haiku" }
|
||||
]
|
||||
},
|
||||
"modes": {
|
||||
"currentValue": "default",
|
||||
"values": [
|
||||
{ "value": "default", "name": "Default" },
|
||||
{ "value": "acceptEdits", "name": "Accept Edits" },
|
||||
{ "value": "plan", "name": "Plan" },
|
||||
{ "value": "dontAsk", "name": "Don't Ask" },
|
||||
{ "value": "bypassPermissions", "name": "Bypass Permissions" }
|
||||
]
|
||||
},
|
||||
"thoughtLevels": { "values": [] }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See [Agent Capabilities](/agent-capabilities) for a full reference of supported models, modes, and thought levels per agent.
|
||||
|
||||
#### api agents install
|
||||
|
||||
```bash
|
||||
sandbox-agent api agents install codex --reinstall
|
||||
```
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ that BoxLite can load directly (BoxLite has its own image store separate from Do
|
|||
```dockerfile
|
||||
FROM node:22-bookworm-slim
|
||||
RUN apt-get update && apt-get install -y curl ca-certificates && rm -rf /var/lib/apt/lists/*
|
||||
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh
|
||||
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
|
||||
RUN sandbox-agent install-agent claude
|
||||
RUN sandbox-agent install-agent codex
|
||||
```
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ cd my-sandbox
|
|||
```dockerfile
|
||||
FROM cloudflare/sandbox:0.7.0
|
||||
|
||||
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh
|
||||
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
|
||||
RUN sandbox-agent install-agent claude && sandbox-agent install-agent codex
|
||||
|
||||
EXPOSE 8000
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ if (process.env.OPENAI_API_KEY) envVars.OPENAI_API_KEY = process.env.OPENAI_API_
|
|||
const sandbox = await daytona.create({ envVars });
|
||||
|
||||
await sandbox.process.executeCommand(
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh"
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"
|
||||
);
|
||||
|
||||
await sandbox.process.executeCommand("sandbox-agent install-agent claude");
|
||||
|
|
@ -64,7 +64,7 @@ if (!hasSnapshot) {
|
|||
name: SNAPSHOT,
|
||||
image: Image.base("ubuntu:22.04").runCommands(
|
||||
"apt-get update && apt-get install -y curl ca-certificates",
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh",
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh",
|
||||
"sandbox-agent install-agent claude",
|
||||
"sandbox-agent install-agent codex",
|
||||
),
|
||||
|
|
|
|||
|
|
@ -16,11 +16,17 @@ docker run --rm -p 3000:3000 \
|
|||
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
|
||||
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
|
||||
alpine:latest sh -c "\
|
||||
apk add --no-cache curl ca-certificates libstdc++ libgcc bash nodejs npm && \
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh && \
|
||||
apk add --no-cache curl ca-certificates libstdc++ libgcc bash && \
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/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"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Alpine is required for some agent binaries that target musl libc.
|
||||
</Note>
|
||||
|
||||
## TypeScript with dockerode
|
||||
|
||||
```typescript
|
||||
|
|
@ -31,18 +37,17 @@ const docker = new Docker();
|
|||
const PORT = 3000;
|
||||
|
||||
const container = await docker.createContainer({
|
||||
Image: "node:22-bookworm-slim",
|
||||
Image: "alpine:latest",
|
||||
Cmd: ["sh", "-c", [
|
||||
"apt-get update",
|
||||
"DEBIAN_FRONTEND=noninteractive apt-get install -y curl ca-certificates bash libstdc++6",
|
||||
"rm -rf /var/lib/apt/lists/*",
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh",
|
||||
"apk add --no-cache curl ca-certificates libstdc++ libgcc bash",
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/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(" && ")],
|
||||
Env: [
|
||||
`ANTHROPIC_API_KEY=${process.env.ANTHROPIC_API_KEY}`,
|
||||
`OPENAI_API_KEY=${process.env.OPENAI_API_KEY}`,
|
||||
`CODEX_API_KEY=${process.env.CODEX_API_KEY}`,
|
||||
].filter(Boolean),
|
||||
ExposedPorts: { [`${PORT}/tcp`]: {} },
|
||||
HostConfig: {
|
||||
|
|
@ -56,7 +61,7 @@ await container.start();
|
|||
const baseUrl = `http://127.0.0.1:${PORT}`;
|
||||
const sdk = await SandboxAgent.connect({ baseUrl });
|
||||
|
||||
const session = await sdk.createSession({ agent: "codex" });
|
||||
const session = await sdk.createSession({ agent: "claude" });
|
||||
await session.prompt([{ type: "text", text: "Summarize this repository." }]);
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ if (process.env.OPENAI_API_KEY) envs.OPENAI_API_KEY = process.env.OPENAI_API_KEY
|
|||
const sandbox = await Sandbox.create({ allowInternetAccess: true, envs });
|
||||
|
||||
await sandbox.commands.run(
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh"
|
||||
"curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"
|
||||
);
|
||||
|
||||
await sandbox.commands.run("sandbox-agent install-agent claude");
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ For local development, run Sandbox Agent directly on your machine.
|
|||
|
||||
```bash
|
||||
# Install
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
|
||||
|
||||
# Run
|
||||
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
|
||||
|
|
@ -20,12 +20,12 @@ Or with npm/Bun:
|
|||
<Tabs>
|
||||
<Tab title="npx">
|
||||
```bash
|
||||
npx @sandbox-agent/cli@0.3.x server --no-token --host 127.0.0.1 --port 2468
|
||||
npx @sandbox-agent/cli@0.2.x server --no-token --host 127.0.0.1 --port 2468
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="bunx">
|
||||
```bash
|
||||
bunx @sandbox-agent/cli@0.3.x server --no-token --host 127.0.0.1 --port 2468
|
||||
bunx @sandbox-agent/cli@0.2.x server --no-token --host 127.0.0.1 --port 2468
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ const run = async (cmd: string, args: string[] = []) => {
|
|||
}
|
||||
};
|
||||
|
||||
await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh"]);
|
||||
await run("sh", ["-c", "curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh"]);
|
||||
await run("sandbox-agent", ["install-agent", "claude"]);
|
||||
await run("sandbox-agent", ["install-agent", "codex"]);
|
||||
|
||||
|
|
|
|||
|
|
@ -51,7 +51,6 @@
|
|||
"pages": [
|
||||
"quickstart",
|
||||
"sdk-overview",
|
||||
"react-components",
|
||||
{
|
||||
"group": "Deploy",
|
||||
"icon": "server",
|
||||
|
|
@ -80,7 +79,7 @@
|
|||
},
|
||||
{
|
||||
"group": "System",
|
||||
"pages": ["file-system", "processes"]
|
||||
"pages": ["file-system"]
|
||||
},
|
||||
{
|
||||
"group": "Orchestration",
|
||||
|
|
@ -95,7 +94,6 @@
|
|||
{
|
||||
"group": "Reference",
|
||||
"pages": [
|
||||
"agent-capabilities",
|
||||
"cli",
|
||||
"inspector",
|
||||
"opencode-compatibility",
|
||||
|
|
|
|||
|
|
@ -34,18 +34,9 @@ console.log(url);
|
|||
- Event JSON inspector
|
||||
- Prompt testing
|
||||
- Request/response debugging
|
||||
- Process management (create, stop, kill, delete, view logs)
|
||||
- Interactive PTY terminal for tty processes
|
||||
- One-shot command execution
|
||||
|
||||
## When to use
|
||||
|
||||
- Development: validate session behavior quickly
|
||||
- Debugging: inspect raw event payloads
|
||||
- Integration work: compare UI behavior with SDK/API calls
|
||||
|
||||
## Process terminal
|
||||
|
||||
The Inspector includes an embedded Ghostty-based terminal for interactive tty
|
||||
processes. The UI uses the SDK's high-level `connectProcessTerminal(...)`
|
||||
wrapper via the shared `@sandbox-agent/react` `ProcessTerminal` component.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "Observability"
|
||||
description: "Track session activity with OpenTelemetry."
|
||||
icon: "chart-line"
|
||||
icon: "terminal"
|
||||
---
|
||||
|
||||
Use OpenTelemetry to instrument session traffic, then ship telemetry to your collector/backend.
|
||||
|
|
|
|||
1201
docs/openapi.json
1201
docs/openapi.json
File diff suppressed because it is too large
Load diff
|
|
@ -1,258 +0,0 @@
|
|||
---
|
||||
title: "Processes"
|
||||
description: "Run commands and manage long-lived processes inside the sandbox."
|
||||
sidebarTitle: "Processes"
|
||||
icon: "terminal"
|
||||
---
|
||||
|
||||
The process API supports:
|
||||
|
||||
- **One-shot execution** — run a command to completion and capture stdout, stderr, and exit code
|
||||
- **Managed processes** — spawn, list, stop, kill, and delete long-lived processes
|
||||
- **Log streaming** — fetch buffered logs or follow live output via SSE
|
||||
- **Terminals** — full PTY support with bidirectional WebSocket I/O
|
||||
- **Configurable limits** — control concurrency, timeouts, and buffer sizes per runtime
|
||||
|
||||
## Run a command
|
||||
|
||||
Execute a command to completion and get its output.
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
|
||||
const sdk = await SandboxAgent.connect({
|
||||
baseUrl: "http://127.0.0.1:2468",
|
||||
});
|
||||
|
||||
const result = await sdk.runProcess({
|
||||
command: "ls",
|
||||
args: ["-la", "/workspace"],
|
||||
});
|
||||
|
||||
console.log(result.exitCode); // 0
|
||||
console.log(result.stdout);
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"command":"ls","args":["-la","/workspace"]}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
You can set a timeout and cap output size:
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
const result = await sdk.runProcess({
|
||||
command: "make",
|
||||
args: ["build"],
|
||||
timeoutMs: 60000,
|
||||
maxOutputBytes: 1048576,
|
||||
});
|
||||
|
||||
if (result.timedOut) {
|
||||
console.log("Build timed out");
|
||||
}
|
||||
if (result.stdoutTruncated) {
|
||||
console.log("Output was truncated");
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes/run" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"command":"make","args":["build"],"timeoutMs":60000,"maxOutputBytes":1048576}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Managed processes
|
||||
|
||||
Create a long-lived process that you can interact with, monitor, and stop later.
|
||||
|
||||
### Create
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
const proc = await sdk.createProcess({
|
||||
command: "node",
|
||||
args: ["server.js"],
|
||||
cwd: "/workspace",
|
||||
});
|
||||
|
||||
console.log(proc.id, proc.pid); // proc_1, 12345
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"command":"node","args":["server.js"],"cwd":"/workspace"}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### List and get
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
const { processes } = await sdk.listProcesses();
|
||||
|
||||
for (const p of processes) {
|
||||
console.log(p.id, p.command, p.status);
|
||||
}
|
||||
|
||||
const proc = await sdk.getProcess("proc_1");
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl "http://127.0.0.1:2468/v1/processes"
|
||||
|
||||
curl "http://127.0.0.1:2468/v1/processes/proc_1"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Stop, kill, and delete
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
// SIGTERM with optional wait
|
||||
await sdk.stopProcess("proc_1", { waitMs: 5000 });
|
||||
|
||||
// SIGKILL
|
||||
await sdk.killProcess("proc_1", { waitMs: 1000 });
|
||||
|
||||
// Remove exited process record
|
||||
await sdk.deleteProcess("proc_1");
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes/proc_1/stop?waitMs=5000"
|
||||
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes/proc_1/kill?waitMs=1000"
|
||||
|
||||
curl -X DELETE "http://127.0.0.1:2468/v1/processes/proc_1"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Logs
|
||||
|
||||
### Fetch buffered logs
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
const logs = await sdk.getProcessLogs("proc_1", {
|
||||
tail: 50,
|
||||
stream: "combined",
|
||||
});
|
||||
|
||||
for (const entry of logs.entries) {
|
||||
console.log(entry.stream, atob(entry.data));
|
||||
}
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl "http://127.0.0.1:2468/v1/processes/proc_1/logs?tail=50&stream=combined"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Follow logs via SSE
|
||||
|
||||
Stream log entries in real time. The subscription replays buffered entries first, then streams new output as it arrives.
|
||||
|
||||
```ts TypeScript
|
||||
const sub = await sdk.followProcessLogs("proc_1", (entry) => {
|
||||
console.log(entry.stream, atob(entry.data));
|
||||
});
|
||||
|
||||
// Later, stop following
|
||||
sub.close();
|
||||
await sub.closed;
|
||||
```
|
||||
|
||||
## Terminals
|
||||
|
||||
Create a process with `tty: true` to allocate a pseudo-terminal, then connect via WebSocket for full bidirectional I/O.
|
||||
|
||||
```ts TypeScript
|
||||
const proc = await sdk.createProcess({
|
||||
command: "bash",
|
||||
tty: true,
|
||||
});
|
||||
```
|
||||
|
||||
### Write input
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
await sdk.sendProcessInput("proc_1", {
|
||||
data: "echo hello\n",
|
||||
encoding: "utf8",
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes/proc_1/input" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"data":"echo hello\n","encoding":"utf8"}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Connect to a terminal
|
||||
|
||||
Use `ProcessTerminalSession` unless you need direct frame access.
|
||||
|
||||
```ts TypeScript
|
||||
const terminal = sdk.connectProcessTerminal("proc_1");
|
||||
|
||||
terminal.onReady(() => {
|
||||
terminal.resize({ cols: 120, rows: 40 });
|
||||
terminal.sendInput("ls\n");
|
||||
});
|
||||
|
||||
terminal.onData((bytes) => {
|
||||
process.stdout.write(new TextDecoder().decode(bytes));
|
||||
});
|
||||
|
||||
terminal.onExit((status) => {
|
||||
console.log("exit:", status.exitCode);
|
||||
});
|
||||
|
||||
terminal.onError((error) => {
|
||||
console.error(error instanceof Error ? error.message : error.message);
|
||||
});
|
||||
|
||||
terminal.onClose(() => {
|
||||
console.log("terminal closed");
|
||||
});
|
||||
```
|
||||
|
||||
Since the browser WebSocket API cannot send custom headers, the endpoint accepts an `access_token` query parameter for authentication. The SDK handles this automatically.
|
||||
|
||||
### Browser terminal emulators
|
||||
|
||||
The terminal session works with any browser terminal emulator like ghostty-web or xterm.js. For a drop-in React terminal, see [React Components](/react-components).
|
||||
|
||||
## Configuration
|
||||
|
||||
Adjust runtime limits like max concurrent processes, timeouts, and buffer sizes.
|
||||
|
||||
<CodeGroup>
|
||||
```ts TypeScript
|
||||
const config = await sdk.getProcessConfig();
|
||||
console.log(config);
|
||||
|
||||
await sdk.setProcessConfig({
|
||||
...config,
|
||||
maxConcurrentProcesses: 32,
|
||||
defaultRunTimeoutMs: 60000,
|
||||
});
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl "http://127.0.0.1:2468/v1/processes/config"
|
||||
|
||||
curl -X POST "http://127.0.0.1:2468/v1/processes/config" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"maxConcurrentProcesses":32,"defaultRunTimeoutMs":60000,"maxRunTimeoutMs":300000,"maxOutputBytes":1048576,"maxLogBytesPerProcess":10485760,"maxInputBytesPerRequest":65536}'
|
||||
```
|
||||
</CodeGroup>
|
||||
|
|
@ -84,7 +84,7 @@ icon: "rocket"
|
|||
Install and run the binary directly.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.3.x/install.sh | sh
|
||||
curl -fsSL https://releases.rivet.dev/sandbox-agent/0.2.x/install.sh | sh
|
||||
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
|
||||
```
|
||||
</Tab>
|
||||
|
|
@ -93,7 +93,7 @@ icon: "rocket"
|
|||
Run without installing globally.
|
||||
|
||||
```bash
|
||||
npx @sandbox-agent/cli@0.3.x server --no-token --host 0.0.0.0 --port 2468
|
||||
npx @sandbox-agent/cli@0.2.x server --no-token --host 0.0.0.0 --port 2468
|
||||
```
|
||||
</Tab>
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ icon: "rocket"
|
|||
Run without installing globally.
|
||||
|
||||
```bash
|
||||
bunx @sandbox-agent/cli@0.3.x server --no-token --host 0.0.0.0 --port 2468
|
||||
bunx @sandbox-agent/cli@0.2.x server --no-token --host 0.0.0.0 --port 2468
|
||||
```
|
||||
</Tab>
|
||||
|
||||
|
|
@ -109,7 +109,7 @@ icon: "rocket"
|
|||
Install globally, then run.
|
||||
|
||||
```bash
|
||||
npm install -g @sandbox-agent/cli@0.3.x
|
||||
npm install -g @sandbox-agent/cli@0.2.x
|
||||
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
|
||||
```
|
||||
</Tab>
|
||||
|
|
@ -118,7 +118,7 @@ icon: "rocket"
|
|||
Install globally, then run.
|
||||
|
||||
```bash
|
||||
bun add -g @sandbox-agent/cli@0.3.x
|
||||
bun add -g @sandbox-agent/cli@0.2.x
|
||||
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
|
||||
bun pm -g trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
|
||||
sandbox-agent server --no-token --host 0.0.0.0 --port 2468
|
||||
|
|
@ -129,7 +129,7 @@ icon: "rocket"
|
|||
For local development, use `SandboxAgent.start()` to spawn and manage the server as a subprocess.
|
||||
|
||||
```bash
|
||||
npm install sandbox-agent@0.3.x
|
||||
npm install sandbox-agent@0.2.x
|
||||
```
|
||||
|
||||
```typescript
|
||||
|
|
@ -143,7 +143,7 @@ icon: "rocket"
|
|||
For local development, use `SandboxAgent.start()` to spawn and manage the server as a subprocess.
|
||||
|
||||
```bash
|
||||
bun add sandbox-agent@0.3.x
|
||||
bun add sandbox-agent@0.2.x
|
||||
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
|
||||
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,103 +0,0 @@
|
|||
---
|
||||
title: "React Components"
|
||||
description: "Drop-in React components for Sandbox Agent frontends."
|
||||
icon: "react"
|
||||
---
|
||||
|
||||
`@sandbox-agent/react` exposes small React components built on top of the `sandbox-agent` SDK.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/react@0.3.x
|
||||
```
|
||||
|
||||
## Full example
|
||||
|
||||
This example connects to a running Sandbox Agent server, starts a tty shell, renders `ProcessTerminal`, and cleans up the process when the component unmounts.
|
||||
|
||||
```tsx TerminalPane.tsx expandable highlight={5,32-36,71}
|
||||
"use client";
|
||||
|
||||
import { useEffect, useState } from "react";
|
||||
import { SandboxAgent } from "sandbox-agent";
|
||||
import { ProcessTerminal } from "@sandbox-agent/react";
|
||||
|
||||
export default function TerminalPane() {
|
||||
const [client, setClient] = useState<SandboxAgent | null>(null);
|
||||
const [processId, setProcessId] = useState<string | null>(null);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
let cancelled = false;
|
||||
let sdk: SandboxAgent | null = null;
|
||||
let createdProcessId: string | null = null;
|
||||
|
||||
const cleanup = async () => {
|
||||
if (!sdk || !createdProcessId) {
|
||||
return;
|
||||
}
|
||||
|
||||
await sdk.killProcess(createdProcessId, { waitMs: 1_000 }).catch(() => {});
|
||||
await sdk.deleteProcess(createdProcessId).catch(() => {});
|
||||
};
|
||||
|
||||
const start = async () => {
|
||||
try {
|
||||
sdk = await SandboxAgent.connect({
|
||||
baseUrl: "http://127.0.0.1:2468",
|
||||
});
|
||||
|
||||
const process = await sdk.createProcess({
|
||||
command: "sh",
|
||||
interactive: true,
|
||||
tty: true,
|
||||
});
|
||||
|
||||
if (cancelled) {
|
||||
createdProcessId = process.id;
|
||||
await cleanup();
|
||||
await sdk.dispose();
|
||||
return;
|
||||
}
|
||||
|
||||
createdProcessId = process.id;
|
||||
setClient(sdk);
|
||||
setProcessId(process.id);
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : "Failed to start terminal.";
|
||||
setError(message);
|
||||
}
|
||||
};
|
||||
|
||||
void start();
|
||||
|
||||
return () => {
|
||||
cancelled = true;
|
||||
void cleanup();
|
||||
void sdk?.dispose();
|
||||
};
|
||||
}, []);
|
||||
|
||||
if (error) {
|
||||
return <div>{error}</div>;
|
||||
}
|
||||
|
||||
if (!client || !processId) {
|
||||
return <div>Starting terminal...</div>;
|
||||
}
|
||||
|
||||
return <ProcessTerminal client={client} processId={processId} height={480} />;
|
||||
}
|
||||
```
|
||||
|
||||
## Component
|
||||
|
||||
`ProcessTerminal` attaches to a running tty process.
|
||||
|
||||
- `client`: a `SandboxAgent` client
|
||||
- `processId`: the process to attach to
|
||||
- `height`, `style`, `terminalStyle`: optional layout overrides
|
||||
- `onExit`, `onError`: optional lifecycle callbacks
|
||||
|
||||
See [Processes](/processes) for the lower-level terminal APIs.
|
||||
|
|
@ -11,12 +11,12 @@ The TypeScript SDK is centered on `sandbox-agent` and its `SandboxAgent` class.
|
|||
<Tabs>
|
||||
<Tab title="npm">
|
||||
```bash
|
||||
npm install sandbox-agent@0.3.x
|
||||
npm install sandbox-agent@0.2.x
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="bun">
|
||||
```bash
|
||||
bun add sandbox-agent@0.3.x
|
||||
bun add sandbox-agent@0.2.x
|
||||
# Allow Bun to run postinstall scripts for native binaries (required for SandboxAgent.start()).
|
||||
bun pm trust @sandbox-agent/cli-linux-x64 @sandbox-agent/cli-linux-arm64 @sandbox-agent/cli-darwin-arm64 @sandbox-agent/cli-darwin-x64 @sandbox-agent/cli-win32-x64
|
||||
```
|
||||
|
|
@ -26,13 +26,7 @@ The TypeScript SDK is centered on `sandbox-agent` and its `SandboxAgent` class.
|
|||
## Optional persistence drivers
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/persist-indexeddb@0.3.x @sandbox-agent/persist-sqlite@0.3.x @sandbox-agent/persist-postgres@0.3.x
|
||||
```
|
||||
|
||||
## Optional React components
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/react@0.3.x
|
||||
npm install @sandbox-agent/persist-indexeddb@0.2.x @sandbox-agent/persist-sqlite@0.2.x @sandbox-agent/persist-postgres@0.2.x
|
||||
```
|
||||
|
||||
## Create a client
|
||||
|
|
@ -45,8 +39,6 @@ const sdk = await SandboxAgent.connect({
|
|||
});
|
||||
```
|
||||
|
||||
`SandboxAgent.connect(...)` now waits for `/v1/health` by default before other SDK requests proceed. To disable that gate, pass `waitForHealth: false`. To keep the default gate but fail after a bounded wait, pass `waitForHealth: { timeoutMs: 120_000 }`. To cancel the startup wait early, pass `signal: abortController.signal`.
|
||||
|
||||
With a custom fetch handler (for example, proxying requests inside Workers):
|
||||
|
||||
```ts
|
||||
|
|
@ -55,19 +47,6 @@ const sdk = await SandboxAgent.connect({
|
|||
});
|
||||
```
|
||||
|
||||
With an abort signal for the startup health gate:
|
||||
|
||||
```ts
|
||||
const controller = new AbortController();
|
||||
|
||||
const sdk = await SandboxAgent.connect({
|
||||
baseUrl: "http://127.0.0.1:2468",
|
||||
signal: controller.signal,
|
||||
});
|
||||
|
||||
controller.abort();
|
||||
```
|
||||
|
||||
With persistence:
|
||||
|
||||
```ts
|
||||
|
|
@ -121,25 +100,6 @@ await restored.prompt([{ type: "text", text: "Continue from previous context." }
|
|||
await sdk.destroySession(restored.id);
|
||||
```
|
||||
|
||||
## Session configuration
|
||||
|
||||
Set model, mode, or thought level at creation or on an existing session:
|
||||
|
||||
```ts
|
||||
const session = await sdk.createSession({
|
||||
agent: "codex",
|
||||
model: "gpt-5.3-codex",
|
||||
});
|
||||
|
||||
await session.setModel("gpt-5.2-codex");
|
||||
await session.setMode("auto");
|
||||
|
||||
const options = await session.getConfigOptions();
|
||||
const modes = await session.getModes();
|
||||
```
|
||||
|
||||
See [Agent Sessions](/agent-sessions) for full details on config options and error handling.
|
||||
|
||||
## Events
|
||||
|
||||
Subscribe to live events:
|
||||
|
|
@ -210,5 +170,14 @@ Parameters:
|
|||
- `token` (optional): Bearer token for authenticated servers
|
||||
- `headers` (optional): Additional request headers
|
||||
- `fetch` (optional): Custom fetch implementation used by SDK HTTP and ACP calls
|
||||
- `waitForHealth` (optional, defaults to enabled): waits for `/v1/health` before HTTP helpers and ACP session setup proceed; pass `false` to disable or `{ timeoutMs }` to bound the wait
|
||||
- `signal` (optional): aborts the startup `/v1/health` wait used by `connect()`
|
||||
|
||||
## Types
|
||||
|
||||
```ts
|
||||
import type {
|
||||
AgentInfo,
|
||||
HealthResponse,
|
||||
SessionEvent,
|
||||
SessionRecord,
|
||||
} from "sandbox-agent";
|
||||
```
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ const sdk = await SandboxAgent.connect({
|
|||
Recommended for sandbox orchestration with actor state.
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/persist-rivet@0.3.x
|
||||
npm install @sandbox-agent/persist-rivet@0.2.x
|
||||
```
|
||||
|
||||
```ts
|
||||
|
|
@ -90,7 +90,7 @@ export default actor({
|
|||
Best for browser apps that should survive reloads.
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/persist-indexeddb@0.3.x
|
||||
npm install @sandbox-agent/persist-indexeddb@0.2.x
|
||||
```
|
||||
|
||||
```ts
|
||||
|
|
@ -112,7 +112,7 @@ const sdk = await SandboxAgent.connect({
|
|||
Best for local/server Node apps that need durable storage without a DB server.
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/persist-sqlite@0.3.x
|
||||
npm install @sandbox-agent/persist-sqlite@0.2.x
|
||||
```
|
||||
|
||||
```ts
|
||||
|
|
@ -134,7 +134,7 @@ const sdk = await SandboxAgent.connect({
|
|||
Use when you already run Postgres and want shared relational storage.
|
||||
|
||||
```bash
|
||||
npm install @sandbox-agent/persist-postgres@0.3.x
|
||||
npm install @sandbox-agent/persist-postgres@0.2.x
|
||||
```
|
||||
|
||||
```ts
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue