Merge remote-tracking branch 'origin/main' into feat/support-pi

# Conflicts: # server/packages/sandbox-agent/src/lib.rs # server/packages/sandbox-agent/src/router.rs
2026-04-15 08:03:46 +00:00 · 2026-02-05 17:09:51 -05:00 · 2026-02-05 17:09:51 -05:00 · a744a8086a
commit a744a8086a
parent 843498e9db 375d73e4cb
67 changed files with 18830 additions and 375 deletions
--- a/docs/cli.mdx
+++ b/docs/cli.mdx
@ -29,6 +29,12 @@ sandbox-agent server [OPTIONS]
 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.
+
+HTTP request logging is enabled by default. Control it with:
+- `SANDBOX_AGENT_LOG_HTTP=0` to disable request logs
+- `SANDBOX_AGENT_LOG_HTTP_HEADERS=1` to include request headers (Authorization is redacted)
+
 ---

 ## Install Agent (Local)
@ -49,6 +55,31 @@ sandbox-agent install-agent claude --reinstall

 ---

+## OpenCode (Experimental)
+
+Start a sandbox-agent server and attach an OpenCode session (uses `opencode attach`):
+
+```bash
+sandbox-agent opencode [OPTIONS]
+```
+
+| 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 |
+| `--session-title <TITLE>` | - | Title for the OpenCode session |
+| `--opencode-bin <PATH>` | - | Override `opencode` binary path |
+
+```bash
+sandbox-agent opencode --token "$TOKEN"
+```
+
+Requires the `opencode` binary to be installed (or set `OPENCODE_BIN` / `--opencode-bin`).
+
+---
+
 ## Credentials

 ### Extract
--- a/docs/docs.json
+++ b/docs/docs.json
@ -41,7 +41,7 @@
 		"pages": [
 			{
 				"group": "Getting started",
-				"pages": ["quickstart", "building-chat-ui", "manage-sessions"]
+				"pages": ["quickstart", "building-chat-ui", "manage-sessions", "opencode-compatibility"]
 			},
 			{
 				"group": "Deploy",
@ -61,11 +61,11 @@
 			},
 			{
 				"group": "Reference",
-				"pages": [
-					"cli",
-					"inspector",
-					"session-transcript-schema",
-					"cors",
+					"pages": [
+						"cli",
+						"inspector",
+						"session-transcript-schema",
+						"cors",
 					{
 						"group": "AI",
 						"pages": ["ai/skill", "ai/llms-txt"]
--- a/docs/opencode-compatibility.mdx
+++ b/docs/opencode-compatibility.mdx
@ -0,0 +1,142 @@
+---
+title: "OpenCode SDK & UI Support"
+description: "Connect OpenCode clients, SDKs, and web UI to Sandbox Agent."
+icon: "rectangle-terminal"
+---
+
+<Warning>
+  **Experimental**: OpenCode SDK & UI support is experimental and may change without notice.
+</Warning>
+
+Sandbox Agent exposes an OpenCode-compatible API, allowing you to connect any OpenCode client, SDK, or web UI to control coding agents running inside sandboxes.
+
+## Why Use OpenCode Clients with Sandbox Agent?
+
+OpenCode provides a rich ecosystem of clients:
+
+- **OpenCode CLI** (`opencode attach`): Terminal-based interface
+- **OpenCode Web UI**: Browser-based chat interface
+- **OpenCode SDK** (`@opencode-ai/sdk`): Rich TypeScript SDK
+
+## Quick Start
+
+### Using OpenCode CLI & TUI
+
+Sandbox Agent provides an all-in-one command to setup Sandbox Agent and connect an OpenCode session, great for local development:
+
+```bash
+sandbox-agent opencode --port 2468 --no-token
+```
+
+Or, start the server and attach separately:
+
+```bash
+# Start sandbox-agent
+sandbox-agent server --no-token --host 127.0.0.1 --port 2468
+
+# Attach OpenCode CLI
+opencode attach http://localhost:2468/opencode
+```
+
+With authentication enabled:
+
+```bash
+# Start with token
+sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
+
+# Attach with password
+opencode attach http://localhost:2468/opencode --password "$SANDBOX_TOKEN"
+```
+
+### Using the OpenCode Web UI
+
+The OpenCode web UI can connect to Sandbox Agent for a full browser-based experience.
+
+<Steps>
+  <Step title="Start Sandbox Agent with CORS">
+    ```bash
+    sandbox-agent server --no-token --host 127.0.0.1 --port 2468 --cors-allow-origin http://127.0.0.1:5173
+    ```
+  </Step>
+  <Step title="Clone and Start the OpenCode Web App">
+    ```bash
+    git clone https://github.com/opencode-ai/opencode
+    cd opencode/packages/app
+    export VITE_OPENCODE_SERVER_HOST=127.0.0.1
+    export VITE_OPENCODE_SERVER_PORT=2468
+    bun run dev -- --host 127.0.0.1 --port 5173
+    ```
+  </Step>
+  <Step title="Open the UI">
+    Navigate to `http://127.0.0.1:5173/` in your browser.
+  </Step>
+</Steps>
+
+<Note>
+  If you see `Error: Could not connect to server`, check that:
+  - The sandbox-agent server is running
+  - `--cors-allow-origin` matches the **exact** browser origin (`localhost` and `127.0.0.1` are different origins)
+</Note>
+
+### Using OpenCode SDK
+
+```typescript
+import { createOpencodeClient } from "@opencode-ai/sdk";
+
+const client = createOpencodeClient({
+  baseUrl: "http://localhost:2468/opencode",
+  headers: { Authorization: "Bearer YOUR_TOKEN" }, // if using auth
+});
+
+// Create a session
+const session = await client.session.create();
+
+// Send a prompt
+await client.session.promptAsync({
+  path: { id: session.data.id },
+  body: {
+    parts: [{ type: "text", text: "Hello, write a hello world script" }],
+  },
+});
+
+// Subscribe to events
+const events = await client.event.subscribe({});
+for await (const event of events.stream) {
+  console.log(event);
+}
+```
+
+## Notes
+
+- **API Routing**: The OpenCode API is available at the `/opencode` base path
+- **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)
+
+## Endpoint Coverage
+
+See the full endpoint compatibility table below. Most endpoints are functional for session management, messaging, and event streaming. Some endpoints return stub responses for features not yet implemented.
+
+<Accordion title="Endpoint Status Table">
+
+| Endpoint | Status | Notes |
+|---|---|---|
+| `GET /event` | ✓ | Emits events for session/message updates (SSE) |
+| `GET /global/event` | ✓ | Wraps events in GlobalEvent format (SSE) |
+| `GET /session` | ✓ | In-memory session store |
+| `POST /session` | ✓ | Create new sessions |
+| `GET /session/{id}` | ✓ | Get session details |
+| `POST /session/{id}/message` | ✓ | Send messages to session |
+| `GET /session/{id}/message` | ✓ | Get session messages |
+| `GET /permission` | ✓ | List pending permissions |
+| `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 /agent` | − | Returns agent list |
+| `GET /config` | − | Returns config |
+| *other endpoints* | − | Return empty/stub responses |
+
+✓ Functional &nbsp;&nbsp; − Stubbed
+
+</Accordion>