docs: add OpenCode SDK & UI Support documentation (experimental)

2026-04-15 12:03:53 +00:00 · 2026-02-05 12:14:01 -08:00 · 2026-02-05 12:14:01 -08:00 · 202d718da7
commit 202d718da7
parent 5d856abe88
5 changed files with 176 additions and 110 deletions
--- a/docs/opencode-sdk-ui-support.mdx
+++ b/docs/opencode-sdk-ui-support.mdx
@ -0,0 +1,148 @@
+---
+title: "OpenCode SDK & UI Support"
+description: "Connect OpenCode clients, SDKs, and web UI to Sandbox Agent."
+---
+
+<Warning>
+  **Experimental**: OpenCode SDK & UI support is experimental and may change without notice.
+</Warning>
+
+Sandbox Agent exposes an OpenCode-compatible API at `/opencode`, 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 SDK** (`@opencode-ai/sdk`) - Programmatic TypeScript access
+- **OpenCode Web UI** - Browser-based chat interface
+
+By connecting these to Sandbox Agent, you get:
+- Control over multiple coding agents (Claude Code, Codex, OpenCode, Amp) through familiar OpenCode tooling
+- Remote sandbox execution with local UI experience
+- Full streaming, permissions, and human-in-the-loop support
+
+## Quick Start
+
+### Using OpenCode CLI
+
+```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:
+
+```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 All-in-One Command
+
+Sandbox Agent can start the server and attach OpenCode automatically:
+
+```bash
+sandbox-agent opencode --port 2468 --no-token
+```
+
+### 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);
+}
+```
+
+## Running the OpenCode Web UI
+
+The OpenCode web UI can connect to Sandbox Agent for a full browser-based experience.
+
+### 1. 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
+```
+
+### 2. Start the OpenCode Web App
+
+Clone and run the OpenCode web app:
+
+```bash
+cd /path/to/opencode/packages/app
+VITE_OPENCODE_SERVER_HOST=127.0.0.1 VITE_OPENCODE_SERVER_PORT=2468 \
+  bun run dev -- --host 127.0.0.1 --port 5173
+```
+
+### 3. Open the UI
+
+Navigate to `http://127.0.0.1:5173/` in your browser.
+
+## API Routing
+
+The OpenCode API is exposed at two locations:
+
+| Path | Description |
+|------|-------------|
+| `/opencode/*` | Nested under `/opencode` prefix |
+| `/*` | Also available at root level |
+
+The root-level routing exists because the OpenCode SDK uses absolute paths internally. Both work identically.
+
+## Notes
+
+- **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">
+
+| Method | Path | Status | Notes |
+|---|---|---|---|
+| GET | /event | SSE | Emits events for session/message updates |
+| GET | /global/event | SSE | Wraps events in GlobalEvent format |
+| GET | /session | Stateful | In-memory session store |
+| POST | /session | Stateful | Create new sessions |
+| GET | /session/{id} | Stateful | Get session details |
+| POST | /session/{id}/message | Stateful | Send messages to session |
+| GET | /session/{id}/message | Stateful | Get session messages |
+| GET | /permission | Stateful | List pending permissions |
+| POST | /permission/{id}/reply | Stateful | Respond to permission requests |
+| GET | /question | Stateful | List pending questions |
+| POST | /question/{id}/reply | Stateful | Answer agent questions |
+| GET | /provider | Stubbed | Returns provider metadata |
+| GET | /agent | Stubbed | Returns agent list |
+| GET | /config | Stubbed | Returns config |
+| *other endpoints* | Stubbed | Return empty/stub responses |
+
+</Accordion>