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

docs: improve OpenCode compatibility docs and fix website feature grid layout

Browse source
This commit is contained in:
Nathan Flurry 2026-02-05 13:41:35 -08:00
parent e87290ea73
commit 375d73e4cb
3 changed files with 89 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -34,7 +34,7 @@ Sandbox Agent solves three problems:
- **Runs Inside Any Sandbox**: Lightweight static Rust binary. One curl command to install inside E2B, Daytona, Vercel Sandboxes, or Docker - **Runs Inside Any Sandbox**: Lightweight static Rust binary. One curl command to install inside E2B, Daytona, Vercel Sandboxes, or Docker
- **Server or SDK Mode**: Run as an HTTP server or embed with the TypeScript SDK - **Server or SDK Mode**: Run as an HTTP server or embed with the TypeScript SDK
- **OpenAPI Spec**: [Well documented](https://sandboxagent.dev/docs/api-reference) and easy to integrate from any language - **OpenAPI Spec**: [Well documented](https://sandboxagent.dev/docs/api-reference) and easy to integrate from any language
- **OpenCode SDK & UI Support** *(Experimental)*: Connect OpenCode CLI, SDK, or web UI to control agents through familiar OpenCode tooling - **OpenCode SDK & UI Support** *(Experimental)*: [Connect OpenCode CLI, SDK, or web UI](https://sandboxagent.dev/docs/opencode-compatibility) to control agents through familiar OpenCode tooling
## Architecture ## Architecture

129
docs/opencode-compatibility.mdx
View file

@ -8,23 +8,27 @@ icon: "rectangle-terminal"
**Experimental**: OpenCode SDK & UI support is experimental and may change without notice. **Experimental**: OpenCode SDK & UI support is experimental and may change without notice.
</Warning> </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. 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? ## Why Use OpenCode Clients with Sandbox Agent?
OpenCode provides a rich ecosystem of clients: 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: - **OpenCode CLI** (`opencode attach`): Terminal-based interface
- Control over multiple coding agents (Claude Code, Codex, OpenCode, Amp) through familiar OpenCode tooling - **OpenCode Web UI**: Browser-based chat interface
- Remote sandbox execution with local UI experience - **OpenCode SDK** (`@opencode-ai/sdk`): Rich TypeScript SDK
- Full streaming, permissions, and human-in-the-loop support
## Quick Start ## Quick Start
### Using OpenCode CLI ### 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 ```bash
# Start sandbox-agent # Start sandbox-agent
@ -34,7 +38,7 @@ sandbox-agent server --no-token --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode opencode attach http://localhost:2468/opencode
``` ```
With authentication: With authentication enabled:
```bash ```bash
# Start with token # Start with token
@ -44,13 +48,35 @@ sandbox-agent server --token "$SANDBOX_TOKEN" --host 127.0.0.1 --port 2468
opencode attach http://localhost:2468/opencode --password "$SANDBOX_TOKEN" opencode attach http://localhost:2468/opencode --password "$SANDBOX_TOKEN"
``` ```
### Using the All-in-One Command ### Using the OpenCode Web UI
Sandbox Agent can start the server and attach OpenCode automatically: The OpenCode web UI can connect to Sandbox Agent for a full browser-based experience.
```bash <Steps>
sandbox-agent opencode --port 2468 --no-token <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 ### Using OpenCode SDK
@ -80,44 +106,9 @@ for await (const event of events.stream) {
} }
``` ```
## 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 ## 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 - **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` - **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) - **Provider Selection**: Use the provider/model selector in the UI to choose which backing agent to use (claude, codex, opencode, amp)
@ -128,22 +119,24 @@ See the full endpoint compatibility table below. Most endpoints are functional f
<Accordion title="Endpoint Status Table"> <Accordion title="Endpoint Status Table">
| Method | Path | Status | Notes | | Endpoint | Status | Notes |
|---|---|---|---| |---|---|---|
| GET | /event | SSE | Emits events for session/message updates | | `GET /event` | ✓ | Emits events for session/message updates (SSE) |
| GET | /global/event | SSE | Wraps events in GlobalEvent format | | `GET /global/event` | ✓ | Wraps events in GlobalEvent format (SSE) |
| GET | /session | Stateful | In-memory session store | | `GET /session` | ✓ | In-memory session store |
| POST | /session | Stateful | Create new sessions | | `POST /session` | ✓ | Create new sessions |
| GET | /session/{id} | Stateful | Get session details | | `GET /session/{id}` | ✓ | Get session details |
| POST | /session/{id}/message | Stateful | Send messages to session | | `POST /session/{id}/message` | ✓ | Send messages to session |
| GET | /session/{id}/message | Stateful | Get session messages | | `GET /session/{id}/message` | ✓ | Get session messages |
| GET | /permission | Stateful | List pending permissions | | `GET /permission` | ✓ | List pending permissions |
| POST | /permission/{id}/reply | Stateful | Respond to permission requests | | `POST /permission/{id}/reply` | ✓ | Respond to permission requests |
| GET | /question | Stateful | List pending questions | | `GET /question` | ✓ | List pending questions |
| POST | /question/{id}/reply | Stateful | Answer agent questions | | `POST /question/{id}/reply` | ✓ | Answer agent questions |
| GET | /provider | Stubbed | Returns provider metadata | | `GET /provider` | − | Returns provider metadata |
| GET | /agent | Stubbed | Returns agent list | | `GET /agent` | − | Returns agent list |
| GET | /config | Stubbed | Returns config | | `GET /config` | − | Returns config |
| *other endpoints* | Stubbed | Return empty/stub responses | | *other endpoints* | − | Return empty/stub responses |
✓ Functional &nbsp;&nbsp; − Stubbed
</Accordion> </Accordion>

54
frontend/packages/website/src/components/FeatureGrid.tsx
View file

@ -91,32 +91,8 @@ export function FeatureGrid() {
</p> </p>
</div> </div>
{/* Managing Sessions */}
<div className="group relative flex flex-col gap-4 overflow-hidden rounded-2xl border border-white/5 bg-zinc-900/30 p-6 backdrop-blur-sm transition-colors duration-500 hover:bg-zinc-900/50">
{/* Top Shine Highlight */}
<div className="absolute left-0 right-0 top-0 z-10 h-[1px] bg-gradient-to-r from-transparent via-white/20 to-transparent" />
{/* Top Left Reflection/Glow */}
<div className="pointer-events-none absolute inset-0 bg-[radial-gradient(circle_at_top_left,rgba(245,158,11,0.15)_0%,transparent_50%)] opacity-0 transition-opacity duration-500 group-hover:opacity-100" />
{/* Sharp Edge Highlight */}
<div className="pointer-events-none absolute left-0 top-0 z-20 h-24 w-24 rounded-tl-2xl border-l border-t border-amber-500 opacity-0 transition-opacity duration-500 [mask-image:linear-gradient(135deg,black_0%,transparent_50%)] group-hover:opacity-100" />
<div className="relative z-10 mb-2 flex items-center gap-3">
<FeatureIcon
icon={Download}
color="text-amber-400"
bgColor="bg-amber-500/10"
hoverBgColor="group-hover:bg-amber-500/20"
glowShadow="group-hover:shadow-[0_0_15px_rgba(245,158,11,0.5)]"
/>
<h4 className="text-sm font-medium uppercase tracking-wider text-white">Automatic Agent Installation</h4>
</div>
<p className="text-zinc-400 text-sm leading-relaxed">
Create sessions, send messages, persist transcripts. Full session lifecycle management over HTTP.
</p>
</div>
{/* Runs Inside Any Sandbox */} {/* Runs Inside Any Sandbox */}
<div className="group relative flex flex-col gap-4 overflow-hidden rounded-2xl border border-white/5 bg-zinc-900/30 p-6 backdrop-blur-sm transition-colors duration-500 hover:bg-zinc-900/50"> <div className="lg:col-span-2 group relative flex flex-col gap-4 overflow-hidden rounded-2xl border border-white/5 bg-zinc-900/30 p-6 backdrop-blur-sm transition-colors duration-500 hover:bg-zinc-900/50">
{/* Top Shine Highlight */} {/* Top Shine Highlight */}
<div className="absolute left-0 right-0 top-0 z-10 h-[1px] bg-gradient-to-r from-transparent via-white/20 to-transparent" /> <div className="absolute left-0 right-0 top-0 z-10 h-[1px] bg-gradient-to-r from-transparent via-white/20 to-transparent" />
{/* Top Left Reflection/Glow */} {/* Top Left Reflection/Glow */}
@ -139,8 +115,32 @@ export function FeatureGrid() {
</p> </p>
</div> </div>
{/* Automatic Agent Installation */}
<div className="lg:col-span-2 group relative flex flex-col gap-4 overflow-hidden rounded-2xl border border-white/5 bg-zinc-900/30 p-6 backdrop-blur-sm transition-colors duration-500 hover:bg-zinc-900/50">
{/* Top Shine Highlight */}
<div className="absolute left-0 right-0 top-0 z-10 h-[1px] bg-gradient-to-r from-transparent via-white/20 to-transparent" />
{/* Top Left Reflection/Glow */}
<div className="pointer-events-none absolute inset-0 bg-[radial-gradient(circle_at_top_left,rgba(245,158,11,0.15)_0%,transparent_50%)] opacity-0 transition-opacity duration-500 group-hover:opacity-100" />
{/* Sharp Edge Highlight */}
<div className="pointer-events-none absolute left-0 top-0 z-20 h-24 w-24 rounded-tl-2xl border-l border-t border-amber-500 opacity-0 transition-opacity duration-500 [mask-image:linear-gradient(135deg,black_0%,transparent_50%)] group-hover:opacity-100" />
<div className="relative z-10 mb-2 flex items-center gap-3">
<FeatureIcon
icon={Download}
color="text-amber-400"
bgColor="bg-amber-500/10"
hoverBgColor="group-hover:bg-amber-500/20"
glowShadow="group-hover:shadow-[0_0_15px_rgba(245,158,11,0.5)]"
/>
<h4 className="text-sm font-medium uppercase tracking-wider text-white">Automatic Agent Installation</h4>
</div>
<p className="text-zinc-400 text-sm leading-relaxed">
Create sessions, send messages, persist transcripts. Full session lifecycle management over HTTP.
</p>
</div>
{/* OpenCode SDK & UI Support */} {/* OpenCode SDK & UI Support */}
<div className="group relative flex flex-col gap-4 overflow-hidden rounded-2xl border border-white/5 bg-zinc-900/30 p-6 backdrop-blur-sm transition-colors duration-500 hover:bg-zinc-900/50"> <div className="lg:col-span-2 group relative flex flex-col gap-4 overflow-hidden rounded-2xl border border-white/5 bg-zinc-900/30 p-6 backdrop-blur-sm transition-colors duration-500 hover:bg-zinc-900/50">
{/* Top Shine Highlight */} {/* Top Shine Highlight */}
<div className="absolute left-0 right-0 top-0 z-10 h-[1px] bg-gradient-to-r from-transparent via-white/20 to-transparent" /> <div className="absolute left-0 right-0 top-0 z-10 h-[1px] bg-gradient-to-r from-transparent via-white/20 to-transparent" />
{/* Top Left Reflection/Glow */} {/* Top Left Reflection/Glow */}
@ -156,7 +156,7 @@ export function FeatureGrid() {
hoverBgColor="group-hover:bg-pink-500/20" hoverBgColor="group-hover:bg-pink-500/20"
glowShadow="group-hover:shadow-[0_0_15px_rgba(236,72,153,0.5)]" glowShadow="group-hover:shadow-[0_0_15px_rgba(236,72,153,0.5)]"
/> />
<h4 className="text-sm font-medium uppercase tracking-wider text-white">OpenCode SDK & UI</h4> <h4 className="text-sm font-medium uppercase tracking-wider text-white">OpenCode SDK & UI Support</h4>
<span className="rounded-full bg-pink-500/20 px-2 py-0.5 text-xs font-medium text-pink-300">Experimental</span> <span className="rounded-full bg-pink-500/20 px-2 py-0.5 text-xs font-medium text-pink-300">Experimental</span>
</div> </div>
<p className="text-zinc-400 text-sm leading-relaxed"> <p className="text-zinc-400 text-sm leading-relaxed">