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

wip: pi working

Browse source
This commit is contained in:
Franklin 2026-02-06 16:54:43 -05:00
commit a6064e7027
120 changed files with 15728 additions and 2301 deletions
Download patch file Download diff file Expand all files Collapse all files

65
docs/cli.mdx
View file

@ -24,12 +24,13 @@ sandbox-agent server [OPTIONS]
| `-A, --cors-allow-header <HEADER>` | all | CORS allowed header (repeatable) |
| `-C, --cors-allow-credentials` | - | Enable CORS credentials |
| `--no-telemetry` | - | Disable anonymous telemetry |
| `--log-to-file` | - | Redirect server logs to a daily log file |
```bash
sandbox-agent server --token "$TOKEN" --port 3000
```
Server logs are redirected to a daily log file under the sandbox-agent data directory (for example, `~/.local/share/sandbox-agent/logs`). Override with `SANDBOX_AGENT_LOG_DIR`, or set `SANDBOX_AGENT_LOG_STDOUT=1` to keep logs on stdout/stderr.
Server logs print to stdout/stderr by default. Use `--log-to-file` or `SANDBOX_AGENT_LOG_TO_FILE=1` to redirect logs to a daily log file under the sandbox-agent data directory (for example, `~/.local/share/sandbox-agent/logs`). Override the directory with `SANDBOX_AGENT_LOG_DIR`, or set `SANDBOX_AGENT_LOG_STDOUT=1` to force stdout/stderr.
HTTP request logging is enabled by default. Control it with:
- `SANDBOX_AGENT_LOG_HTTP=0` to disable request logs
@ -57,7 +58,7 @@ sandbox-agent install-agent claude --reinstall
## OpenCode (Experimental)
Start a sandbox-agent server and attach an OpenCode session (uses `opencode attach`):
Start (or reuse) a sandbox-agent daemon and attach an OpenCode session (uses `opencode attach`):
```bash
sandbox-agent opencode [OPTIONS]
@ -76,7 +77,54 @@ sandbox-agent opencode [OPTIONS]
sandbox-agent opencode --token "$TOKEN"
```
Requires the `opencode` binary to be installed (or set `OPENCODE_BIN` / `--opencode-bin`).
The daemon logs to a per-host log file under the sandbox-agent data directory (for example, `~/.local/share/sandbox-agent/daemon/daemon-127-0-0-1-2468.log`).
Requires the `opencode` binary to be installed (or set `OPENCODE_BIN` / `--opencode-bin`). If it is not found on `PATH`, sandbox-agent installs it automatically.
---
## Daemon
Manage the background daemon. See the [Daemon](/daemon) docs for details on lifecycle and auto-upgrade.
### Start
```bash
sandbox-agent daemon start [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host to bind to |
| `-p, --port <PORT>` | `2468` | Port to bind to |
| `-t, --token <TOKEN>` | - | Authentication token |
| `-n, --no-token` | - | Disable authentication |
```bash
sandbox-agent daemon start --no-token
```
### Stop
```bash
sandbox-agent daemon stop [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
| `-p, --port <PORT>` | `2468` | Port of the daemon |
### Status
```bash
sandbox-agent daemon status [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
| `-p, --port <PORT>` | `2468` | Port of the daemon |
---
@ -169,6 +217,16 @@ sandbox-agent api agents modes <AGENT>
sandbox-agent api agents modes claude
```
#### Get Agent Models
```bash
sandbox-agent api agents models <AGENT>
```
```bash
sandbox-agent api agents models claude
```
---
### Sessions
@ -329,6 +387,7 @@ sandbox-agent api sessions reply-permission my-session perm1 --reply once
| `api agents list` | `GET /v1/agents` |
| `api agents install` | `POST /v1/agents/{agent}/install` |
| `api agents modes` | `GET /v1/agents/{agent}/modes` |
| `api agents models` | `GET /v1/agents/{agent}/models` |
| `api sessions list` | `GET /v1/sessions` |
| `api sessions create` | `POST /v1/sessions/{sessionId}` |
| `api sessions send-message` | `POST /v1/sessions/{sessionId}/messages` |

2
docs/conversion.mdx
View file

@ -84,4 +84,4 @@ Message normalization notes
- If Pi message_update events omit messageId, we synthesize a stable message id and emit a synthetic item.started before the first delta so streaming text stays grouped.
- Pi auto_compaction_start/auto_compaction_end and auto_retry_start/auto_retry_end events are mapped to status items (label `pi.*`).
- Pi extension_ui_request/extension_error events are mapped to status items.
- Pi RPC from pi-coding-agent does not include sessionId in events; we route events to the current Pi session (single-session semantics).
- Pi RPC from pi-coding-agent does not include sessionId in events; each daemon session owns a dedicated Pi RPC process, so events are routed by runtime ownership (parallel sessions supported).

96
docs/daemon.mdx Normal file
View file

@ -0,0 +1,96 @@
---
title: "Daemon"
description: "Background daemon lifecycle, auto-upgrade, and management."
icon: "microchip"
---
The sandbox-agent daemon is a background server process that stays running between sessions. Commands like `sandbox-agent opencode` and `gigacode` automatically start it when needed and restart it when the binary is updated.
## How it works
1. When you run `sandbox-agent opencode`, `sandbox-agent daemon start`, or `gigacode`, the CLI checks if a daemon is already healthy at the configured host and port.
2. If no daemon is running, one is spawned in the background with stdout/stderr redirected to a log file.
3. The CLI writes a PID file and a build ID file to track the running process and its version.
4. On subsequent invocations, if the daemon is still running but was built from a different commit, the CLI automatically stops the old daemon and starts a new one.
## Auto-upgrade
Each build of sandbox-agent embeds a unique **build ID** (the git short hash, or a version-timestamp fallback). When a daemon is started, this build ID is written to a version file alongside the PID file.
On every invocation of `ensure_running` (called by `opencode`, `gigacode`, and `daemon start`), the CLI compares the stored build ID against the current binary's build ID. If they differ, the running daemon is stopped and replaced automatically:
```
daemon outdated (build a1b2c3d -> f4e5d6c), restarting...
```
This means installing a new version of sandbox-agent and running any daemon-aware command is enough to upgrade — no manual restart needed.
## Managing the daemon
### Start
Start a daemon in the background. If one is already running and healthy, this is a no-op.
```bash
sandbox-agent daemon start [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host to bind to |
| `-p, --port <PORT>` | `2468` | Port to bind to |
| `-t, --token <TOKEN>` | - | Authentication token |
| `-n, --no-token` | - | Disable authentication |
```bash
sandbox-agent daemon start --no-token
```
### Stop
Stop a running daemon. Sends SIGTERM and waits up to 5 seconds for a graceful shutdown before falling back to SIGKILL.
```bash
sandbox-agent daemon stop [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
| `-p, --port <PORT>` | `2468` | Port of the daemon |
```bash
sandbox-agent daemon stop
```
### Status
Show whether the daemon is running, its PID, build ID, and log path.
```bash
sandbox-agent daemon status [OPTIONS]
```
| Option | Default | Description |
|--------|---------|-------------|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
| `-p, --port <PORT>` | `2468` | Port of the daemon |
```bash
sandbox-agent daemon status
# Daemon running (PID 12345, build a1b2c3d, logs: ~/.local/share/sandbox-agent/daemon/daemon-127-0-0-1-2468.log)
```
If the daemon was started with an older binary, the status includes an `[outdated, restart recommended]` notice.
## Files
All daemon state files live under the sandbox-agent data directory (typically `~/.local/share/sandbox-agent/daemon/`):
| File | Purpose |
|------|---------|
| `daemon-{host}-{port}.pid` | PID of the running daemon process |
| `daemon-{host}-{port}.version` | Build ID of the running daemon |
| `daemon-{host}-{port}.log` | Daemon stdout/stderr log output |
Multiple daemons can run on different host/port combinations without conflicting.

19
docs/docs.json
View file

@ -41,7 +41,12 @@
"pages": [
{
"group": "Getting started",
"pages": ["quickstart", "building-chat-ui", "manage-sessions", "opencode-compatibility"]
"pages": [
"quickstart",
"building-chat-ui",
"manage-sessions",
"opencode-compatibility"
]
},
{
"group": "Deploy",
@ -61,18 +66,18 @@
},
{
"group": "Reference",
"pages": [
"cli",
"inspector",
"session-transcript-schema",
"cors",
"pages": [
"cli",
"inspector",
"session-transcript-schema",
"gigacode",
{
"group": "AI",
"pages": ["ai/skill", "ai/llms-txt"]
},
{
"group": "Advanced",
"pages": ["telemetry"]
"pages": ["daemon", "cors", "telemetry"]
}
]
},

6
docs/gigacode.mdx Normal file
View file

@ -0,0 +1,6 @@
---
title: Gigacode
url: "https://github.com/rivet-dev/sandbox-agent/tree/main/gigacode"
---

91
docs/openapi.json
View file

@ -10,7 +10,7 @@
"license": {
"name": "Apache-2.0"
},
"version": "0.1.6-rc.1"
"version": "0.1.7"
},
"servers": [
{
@ -102,6 +102,47 @@
}
}
},
"/v1/agents/{agent}/models": {
"get": {
"tags": [
"agents"
],
"operationId": "get_agent_models",
"parameters": [
{
"name": "agent",
"in": "path",
"description": "Agent id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentModelsResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/v1/agents/{agent}/modes": {
"get": {
"tags": [
@ -669,6 +710,7 @@
"mcpTools",
"streamingDeltas",
"itemStarted",
"variants",
"sharedProcess"
],
"properties": {
@ -726,6 +768,9 @@
},
"toolResults": {
"type": "boolean"
},
"variants": {
"type": "boolean"
}
}
},
@ -832,6 +877,50 @@
}
}
},
"AgentModelInfo": {
"type": "object",
"required": [
"id"
],
"properties": {
"defaultVariant": {
"type": "string",
"nullable": true
},
"id": {
"type": "string"
},
"name": {
"type": "string",
"nullable": true
},
"variants": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
}
},
"AgentModelsResponse": {
"type": "object",
"required": [
"models"
],
"properties": {
"defaultModel": {
"type": "string",
"nullable": true
},
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentModelInfo"
}
}
}
},
"AgentModesResponse": {
"type": "object",
"required": [

3
docs/opencode-compatibility.mdx
View file

@ -112,6 +112,7 @@ for await (const event of events.stream) {
- **Authentication**: If sandbox-agent is started with `--token`, include `Authorization: Bearer <token>` header or use `--password` flag with CLI
- **CORS**: When using the web UI from a different origin, configure `--cors-allow-origin`
- **Provider Selection**: Use the provider/model selector in the UI to choose which backing agent to use (claude, codex, opencode, amp)
- **Models & Variants**: Providers are grouped by backing agent (e.g. Claude Code, Codex, Amp). OpenCode models are grouped by `OpenCode (<provider>)` to preserve their native provider grouping. Each model keeps its real model ID, and variants are exposed when available (Codex/OpenCode/Amp).
## Endpoint Coverage
@ -132,7 +133,7 @@ See the full endpoint compatibility table below. Most endpoints are functional f
| `POST /permission/{id}/reply` | ✓ | Respond to permission requests |
| `GET /question` | ✓ | List pending questions |
| `POST /question/{id}/reply` | ✓ | Answer agent questions |
| `GET /provider` | − | Returns provider metadata |
| `GET /provider` | ✓ | Returns provider metadata |
| `GET /agent` | − | Returns agent list |
| `GET /config` | − | Returns config |
| *other endpoints* | − | Return empty/stub responses |

4
docs/session-transcript-schema.mdx
View file

@ -29,6 +29,7 @@ This table shows which agent feature coverage appears in the universal event str
| File Changes | - | ✓ | - | - | |
| MCP Tools | - | ✓ | - | - | |
| Streaming Deltas | ✓ | ✓ | ✓ | - | ✓ |
| Variants | | ✓ | ✓ | ✓ | |
Agents: [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) · [Pi](https://buildwithpi.ai/pi-cli)
@ -76,6 +77,9 @@ Agents: [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude
<Accordion title="Streaming Deltas">
Native streaming of content deltas. When not supported, the daemon emits a single synthetic delta before `item.completed`.
</Accordion>
<Accordion title="Variants">
Model variants such as reasoning effort or depth. Agents may expose different variant sets per model.
</Accordion>
</AccordionGroup>
Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it.