---
title: "OpenCode Compatibility"
description: "Connect OpenCode clients, SDKs, and web UI to Sandbox Agent."
---

<Warning>
  **Experimental**: OpenCode SDK/UI compatibility may change.
</Warning>

Sandbox Agent exposes an OpenCode-compatible API at `/opencode`.

## Why use OpenCode clients with Sandbox Agent?

- OpenCode CLI (`opencode attach`)
- OpenCode web UI
- OpenCode TypeScript SDK (`@opencode-ai/sdk`)

## Quick start

### OpenCode CLI / TUI

```bash
sandbox-agent opencode --port 2468 --no-token
```

Or start server + attach manually:

```bash
sandbox-agent server --no-token --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode
```

With authentication enabled:

```bash
sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode --password "$SANDBOX_TOKEN"
```

### OpenCode web UI

<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="Run OpenCode web app">
    ```bash
    git clone https://github.com/anomalyco/opencode
    cd opencode/packages/app
    export VITE_OPENCODE_SERVER_HOST=127.0.0.1
    export VITE_OPENCODE_SERVER_PORT=2468
    bun install
    bun run dev -- --host 127.0.0.1 --port 5173
    ```
  </Step>
  <Step title="Open UI">
    Visit `http://127.0.0.1:5173/`.
  </Step>
</Steps>

### OpenCode SDK

```typescript
import { createOpencodeClient } from "@opencode-ai/sdk";

const client = createOpencodeClient({
  baseUrl: "http://localhost:2468/opencode",
});

const session = await client.session.create();

await client.session.promptAsync({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Hello, write a hello world script" }],
  },
});

const events = await client.event.subscribe({});
for await (const event of events.stream) {
  console.log(event);
}
```

## Notes

- API base path: `/opencode`
- If server auth is enabled, pass bearer auth (or `--password` in OpenCode CLI)
- For browser UIs, configure CORS with `--cors-allow-origin`
- Provider selector currently exposes compatible providers (`mock`, `amp`, `claude`, `codex`)
- Provider/model metadata for compatibility endpoints is normalized and may differ from native OpenCode grouping
- Optional proxy: set `OPENCODE_COMPAT_PROXY_URL` to forward selected endpoints to native OpenCode

## Endpoint coverage

<Accordion title="Endpoint Status Table">

| Endpoint | Status | Notes |
|---|---|---|
| `GET /event` | ✓ | Session/message updates (SSE) |
| `GET /global/event` | ✓ | GlobalEvent-wrapped stream |
| `GET /session` | ✓ | Session list |
| `POST /session` | ✓ | Create session |
| `GET /session/{id}` | ✓ | Session details |
| `POST /session/{id}/message` | ✓ | Send message |
| `GET /session/{id}/message` | ✓ | Session messages |
| `GET /permission` | ✓ | Pending permissions |
| `POST /permission/{id}/reply` | ✓ | Permission reply |
| `GET /question` | ✓ | Pending questions |
| `POST /question/{id}/reply` | ✓ | Question reply |
| `GET /provider` | ✓ | Provider metadata |
| `GET /command` | ↔ | Proxied when `OPENCODE_COMPAT_PROXY_URL` is set; otherwise stub |
| `GET /config` | ↔ | Proxied when set; otherwise stub |
| `PATCH /config` | ↔ | Proxied when set; otherwise local compatibility behavior |
| `GET /global/config` | ↔ | Proxied when set; otherwise stub |
| `PATCH /global/config` | ↔ | Proxied when set; otherwise local compatibility behavior |
| `/tui/*` | ↔ | Proxied when set; otherwise local compatibility behavior |
| `GET /agent` | − | Agent list |
| *other endpoints* | − | Empty/stub responses |

✓ Functional   ↔ Proxied optional   − Stubbed

</Accordion>