sandbox-agent/docs/opencode-compatibility.mdx

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