From e0f753803c99c322d1fc688770bd50b3b6521bda Mon Sep 17 00:00:00 2001
From: Alex Blank <alexblank@fastmail.com>
Date: Sat, 16 May 2026 11:28:48 +0200
Subject: [PATCH] docs(opencode): add OpenCode tool documentation to
 development guide

- Document manifest configuration and web terminal access
- Add environment variables and workspace mount details
- Include usage instructions and differences from code-server
- Add local testing commands for OpenCode container
---
 docs/development.md | 75 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/docs/development.md b/docs/development.md
index 7a7f8da..761d9d5 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -323,3 +323,78 @@ When a tool instance is spawned:
 ### Validation
 
 Before spawning, the system validates that all required secrets exist. If any are missing, the spawn fails with an error message listing the missing secrets.
+
+## OpenCode Tool
+
+### Overview
+
+OpenCode is an AI-powered terminal-based development environment accessible via web browser. It is included as a built-in tool manifest alongside code-server.
+
+### Manifest
+
+**File:** `apps/api/app/tools/manifests/opencode.yml`
+
+```yaml
+id: opencode
+name: OpenCode
+image: ghcr.io/opencode-ai/opencode:latest
+ports:
+  - container_port: 3000
+    primary: true
+```
+
+### Web Terminal Access
+
+OpenCode exposes a terminal interface on port 3000:
+- **Subdomain:** `opencode-{project}-{user}.{domain}`
+- **Health Check:** `GET /` on port 3000
+- **Terminal:** Full xterm-256color support with color output
+
+### Environment Variables
+
+The following environment variables are configured for terminal support:
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `TERM` | `xterm-256color` | Terminal type with color support |
+| `FORCE_COLOR` | `"1"` | Force color output |
+
+### Workspace Mount
+
+OpenCode mounts the project workspace at `/workspace` for persistent file access.
+
+### Config Mount
+
+User-specific OpenCode configuration is mounted at `/root/.config/opencode`.
+
+### Usage
+
+1. Navigate to `/tools/spawn` in the frontend
+2. Select "OpenCode" from the tool dropdown
+3. Choose a project
+4. Enter an instance name
+5. Click "Spawn Tool"
+6. Once running, click "Open Tool" to access the web terminal
+
+### Differences from code-server
+
+| Feature | OpenCode | code-server |
+|---------|----------|-------------|
+| Interface | Terminal (web-based) | VS Code (web-based) |
+| Port | 3000 | 8080 |
+| Primary Use | Terminal/CLI tasks | Code editing/IDE |
+| AI Features | Built-in AI assistance | Extensions required |
+
+### Local Testing
+
+To test OpenCode locally without the full platform:
+
+```bash
+docker run -it --rm \
+  -p 3000:3000 \
+  -e TERM=xterm-256color \
+  -e FORCE_COLOR=1 \
+  ghcr.io/opencode-ai/opencode:latest
+```
+
+Then open `http://localhost:3000` in your browser.