Note: This is an independent, community-maintained project created by fans of OpenCode. We are not affiliated with SST Corp. or the official OpenCode project. For the official OpenCode CLI, visit opencode.ai.

Last Updated: October 28, 2025

(web)

OC Web - The web interface for OpenCode.

OC Web is a web-based interface for the OpenCode Server API, providing a browser-based way to interact with OpenCode sessions. Built on TanStack Start, React, and Bun, it offers a complete web experience for managing and monitoring OpenCode workflows.

🚀 Quick Start

Option 1: Run with bunx (Recommended)

# Latest stable release
bunx opencode-web@latest

# Dev release (bleeding edge)
bunx opencode-web@dev

Option 2: Install Globally

# Using Bun
bun add -g opencode-web
opencode-web

# Using npm
npm install -g opencode-web
opencode-web

# Using yarn
yarn global add opencode-web
opencode-web

Option 3: One-liner Installer

curl -sSL https://raw.githubusercontent.com/kcrommett/opencode-web/main/install.sh | bash

Once started, open http://localhost:3000 in your browser. The CLI launches a local OpenCode Server by default and wires its URL into the web client automatically. Use the command-line flags to connect to an existing server or adjust the listening host/port without touching environment variables.

Platform Notes:

• On Windows, opencode-web uses your locally installed opencode CLI from PATH.
  • ⚠️ bunx limitation: Cannot auto-launch the bundled server due to Bun's /bin/sh issue. Use --external-server or install locally. See details
  • ✅ Local install: Works perfectly with automatic server launch
• On macOS/Linux, opencode-web uses the bundled OpenCode SDK server (no additional installation required).

⚠️ Security Warning: This application runs without authentication by default. Do not expose it directly to the internet without proper security measures. For secure remote access, consider using Cloudflare Access with Cloudflare Tunnel to add authentication and protect your instance.

Command-line Options

• --external-server <url> – connect to an existing OpenCode Server and skip the bundled instance.
• --no-bundled-server – skip launching the bundled server (requires --external-server or OPENCODE_SERVER_URL).
• -p, --port <number> – port for the web UI (default: 3000).
• -H, --host <hostname> – interface to bind the web UI server to (default: localhost). Use 0.0.0.0 for LAN access.
• -h, --help – show the built-in usage help.

Environment Variables

OpenCode Web uses three canonical environment variables for configuration:

Variable	Description	Default
OPENCODE_SERVER_URL	Full URL to the OpenCode server (scheme + host + port)	http://localhost:4096
OPENCODE_WEB_HOST	Interface to bind the web server to	localhost
OPENCODE_WEB_PORT	Port for the web UI server	3000

Configuration precedence (highest to lowest):

1. CLI flags (--port, --host, --external-server)
2. Canonical environment variables (OPENCODE_*)
3. Legacy environment variables (deprecated, see Migration section)
4. Default values

Legacy variables (deprecated, maintained for backward compatibility):

• PORT → use OPENCODE_WEB_PORT
• HOST → use OPENCODE_WEB_HOST
• VITE_OPENCODE_SERVER_URL → use OPENCODE_SERVER_URL
• OPENCODE_SERVER_PORT → configure via OPENCODE_SERVER_URL
• OPENCODE_SERVER_HOSTNAME → configure via OPENCODE_SERVER_URL

Additional optional variables:

• OPENCODE_WEB_DISABLE_BUNDLED_SERVER: Set to 1, true, yes, or on to skip launching the bundled server
• VITE_BASE_PATH: Base path for reverse proxy deployments
• VITE_PWA_ASSETS_URL: URL prefix for PWA assets when using a CDN
• VITE_ALLOWED_HOSTS: Comma-separated list of allowed hostnames for the dev server
• OPENCODE_WEB_CSS_TRANSFORMER: Choose between postcss (default) or lightningcss

Example: opencode-web --external-server http://10.0.0.200:4096 --host 0.0.0.0 -p 8080

• Runs opencode-web listening on all interfaces at port 8080, connecting to an existing OpenCode Server at http://10.0.0.200:4096

Example: OPENCODE_SERVER_URL=http://10.0.0.200:4096 OPENCODE_WEB_PORT=8080 bun run dev

• Runs opencode-web in development mode on port 8080, connecting to an existing OpenCode Server at http://10.0.0.200:4096

Why a web interface?

• Access OpenCode sessions from any browser without additional software installation
• Real-time monitoring of active sessions with live updates
• Browser-native features like screenshots, downloads, and responsive design
• Ideal for demonstrations, training, and remote collaboration

Feature Highlights

Session continuation anywhere

Reconnect to an existing conversation with full command history, agent context, and pending tasks so you can pick up work between devices.

Live session timeline

Follow model outputs, reasoning traces, and tool runs via Server-Sent Events so you always know what the agent is doing—even from your phone.

Multi-agent command deck

Switch between saved agent presets, route complex tasks to specialists, and keep context switching frictionless from the browser.

Model + command palette

Quick access to different AI models with an intuitive picker interface

File-aware problem solving

Browse project trees, view files, and download artifacts directly from the web interface. Syntax highlighting keeps context rich.

Inline asset preview

Quickly view images and animations in your browser, or download other binary files.

Theme gallery for every setup

Toggle between opencode color palettes to match whatever theme you prefer.

One-tap PWA install

Progressive Web App hooks keep the client a tap away with full-screen, app-like usage—ideal for tablets or a second monitor.

Architecture at a Glance

• TanStack Start + React Router power hybrid SSR/CSR routing with file-based conventions.
• Bun server (server.ts) proxies event streams to the OpenCode backend and serves the compiled client.
• Shared lib layer (src/lib/) wraps the OpenCode HTTP API for seamless integration.
• Composable UI primitives in src/app/_components/ui/ provide a consistent design system.

Important Note for Custom Deployments: Browser access to the OpenCode server must be mediated through the web app. The frontend cannot directly connect to the OpenCode API due to proxy requirements. All requests are routed through the web server's /api/* endpoints to ensure compatibility with external server configurations.

Requirements

• Bun 1.3.x (toolchain pinned in bunfig.toml)
• Node.js 18+ for editor integrations and lint tooling
• OpenCode Server (the CLI bundles one automatically; pass --external-server to reuse an existing instance)

Getting Started

1. Install dependencies

   bun install

2. Configure environment
   The web app resolves configuration using the canonical environment variables. For local development, set OPENCODE_SERVER_URL in .env.local or use the --external-server CLI flag:

   OPENCODE_SERVER_URL=http://localhost:4096

   Or run: bun run dev --external-server http://localhost:4096
3. Run the dev server

   bun run dev

   The app listens on http://localhost:3000. Replace localhost with a LAN IP to check in from another device on the same network.

Production Build & Serve

1. Build the client + SSR bundles

   bun run build

   Compiled assets land in dist/client (static) and dist/server (SSR handler).
2. Serve the production bundle

   bun run start

   The start script executes server.ts, which:
   • Loads the TanStack Start handler from dist/server/server.js
   • Serves static assets from dist/client
   • Proxies /api/events to your OpenCode server for SSE streaming

Set OPENCODE_WEB_PORT, OPENCODE_WEB_HOST, OPENCODE_SERVER_URL, or NODE_ENV to customize runtime behavior. Configuration is resolved at runtime using the precedence order described in the Environment Variables section.

Windows Build Troubleshooting

If you encounter Cannot find module errors when building on Windows (e.g., @rollup/rollup-win32-x64-msvc or @tailwindcss/oxide-win32-x64-msvc):

1. Clear node_modules and reinstall:

   rm -rf node_modules
   bun install

   These errors occur when lockfiles created on Linux/macOS omit Windows-specific platform binaries. The project now explicitly includes Windows binaries in optionalDependencies to prevent this issue (npm/cli#4828).

2. If the error persists after reinstalling, ensure you're using the latest version of the repository with updated lockfiles that include:

   • @rollup/rollup-win32-x64-msvc (64-bit Intel/AMD)
   • @rollup/rollup-win32-arm64-msvc (64-bit ARM, e.g., Surface devices)
   • @tailwindcss/oxide-win32-x64-msvc (64-bit Intel/AMD)
   • @tailwindcss/oxide-win32-arm64-msvc (64-bit ARM, e.g., Surface devices)

Windows + bunx Limitation

⚠️ Important: bunx opencode-web on Windows cannot automatically launch the bundled OpenCode Server due to a Bun runtime limitation with /bin/sh remapping. You must either use an external server or install locally.

The Issue

When running bunx opencode-web@latest on Windows, the bundled OpenCode Server fails to start with:

error: interpreter executable "/bin/sh" not found in %PATH%
[ERROR] Failed to start OpenCode Server.

This happens because:

• bunx creates temporary installations that don't properly install the Windows OpenCode binary
• Bun's current Windows implementation cannot find /bin/sh when spawning the bundled server process
• The bundled server requires the opencode CLI, which fails under these conditions

Recommended Workarounds

Option 1: Use an External OpenCode Server (Easiest for bunx)

First, start an OpenCode server separately:

# Install OpenCode CLI globally if you haven't already
# Download from: https://github.com/opencode-ai/opencode

# Start the server
opencode serve --hostname=127.0.0.1 --port=4096

Then run opencode-web pointing to it:

bunx opencode-web@latest --external-server http://127.0.0.1:4096

Option 2: Install Locally (Recommended for regular use)

Install the package locally so Windows binaries are properly resolved:

# Create a directory and install
mkdir my-opencode-web
cd my-opencode-web
bun install opencode-web

# IMPORTANT: Run the binary directly on Windows
bun run packages/opencode-web/bin/opencode-web.js

Or install globally:

bun add -g opencode-web
# Then run the binary directly
opencode-web

⚠️ Important Note for Windows: When installing locally, you must run the binary directly (bun run packages/opencode-web/bin/opencode-web.js) rather than using the npm script (bun run opencode-web). The npm script may still encounter the same /bin/sh limitation. Running the binary directly ensures proper Windows binary resolution.

Option 3: Build from Source (For contributors or advanced users)

git clone https://github.com/sst/opencode-web
cd opencode-web
bun install
bun run build
bun run packages/opencode-web/bin/opencode-web.js

Other Platforms

This limitation only affects Windows users running via bunx:

• ✅ macOS/Linux + bunx: Works perfectly (uses bundled SDK)
• ✅ Windows + local install: Works perfectly (proper binary resolution)
• ⚠️ Windows + bunx: Requires --external-server flag

Technical Details

The CLI detects bunx on Windows and exits early with actionable guidance. If you see the error, it means:

1. You're on Windows
2. Running from a bunx temporary directory
3. No --external-server flag was provided

For more information about this Bun limitation, see:

• Bun issue tracking: oven-sh/bun#issues (to be filed - search for "/bin/sh Windows")
• OpenCode upstream: sst/opencode#issues (to be filed - search for "Windows bunx")
• OpenCode Server: https://github.com/sst/opencode

Troubleshooting

If you encounter errors even with --external-server:

1. Verify the server is running:

   # Test the server URL
   curl http://127.0.0.1:4096/health

2. Check firewall settings: Ensure localhost connections are allowed

3. Try a different port: If 4096 is in use, start the server on another port:

   opencode serve --hostname=127.0.0.1 --port=4097
   bunx opencode-web@latest --external-server http://127.0.0.1:4097

4. Use host IP instead of localhost: Sometimes 127.0.0.1 works better than localhost on Windows

Migration Guide: Environment Variables

If you're upgrading from an earlier version, OpenCode Web has simplified configuration to three canonical environment variables. Legacy variables are still supported but deprecated.

Quick Migration

Old Variable	New Variable	Notes
PORT	OPENCODE_WEB_PORT	Same meaning, new name
HOST	OPENCODE_WEB_HOST	Same meaning, new name
VITE_OPENCODE_SERVER_URL	OPENCODE_SERVER_URL	Same meaning, shorter name
OPENCODE_SERVER_PORT	OPENCODE_SERVER_URL	Now specify full URL (e.g., http://localhost:4096)
OPENCODE_SERVER_HOSTNAME	OPENCODE_SERVER_URL	Now specify full URL (e.g., http://localhost:4096)

Example Migrations

Before:

PORT=3000
HOST=0.0.0.0
VITE_OPENCODE_SERVER_URL=http://10.0.0.5:5000

After:

OPENCODE_WEB_PORT=3000
OPENCODE_WEB_HOST=0.0.0.0
OPENCODE_SERVER_URL=http://10.0.0.5:5000

Before (bundled server config):

OPENCODE_SERVER_PORT=5002
OPENCODE_SERVER_HOSTNAME=192.168.1.100

After:

OPENCODE_SERVER_URL=http://192.168.1.100:5002

Deprecation Warnings

When using legacy variables in development mode, you'll see warnings like:

[deprecate] PORT is deprecated, prefer OPENCODE_WEB_PORT

These warnings do not appear in production. Update your configuration at your convenience—legacy variables will continue to work during the transition period.

Project Structure

src/
├── app/                        # TanStack Start routes & UI components
│   └── _components/            # Message renderers, UI primitives, dialogs, pickers
├── contexts/                   # React contexts for session + theme state
├── hooks/                      # Reusable hooks around OpenCode data flows
├── lib/                        # HTTP client, command parser, theme helpers
├── router.tsx                  # Router configuration
server.ts                       # Bun production server wrapper
vite.config.ts                  # Vite + TanStack Start configuration

Key entry points include:

• src/lib/opencode-server-fns.ts – server-side wrappers for the OpenCode HTTP API
• src/app/_components/message/ – renders reasoning, snapshots, tool output, and patches
• src/app/_components/ui/ – button, dialog, picker, and form controls

Helpful Commands

• bun run dev – launch the development server with hot reload
• bun run build – produce production-ready client + SSR bundles
• bun run start – serve the compiled build via the Bun runtime
• bun run lint – enforce shared ESLint rules
• bun x tsc --noEmit – typecheck without generating artifacts
• bun run test – run Playwright smoke tests when present

Development Notes

• Silence logs in production by guarding with if (process.env.NODE_ENV !== "production").
• Favor Bun utilities (e.g., Bun.file) in shared helpers when they simplify IO or streaming.
• Keep server function schemas synced with the OpenCode SDK.
• Confirm UI changes in both desktop and mobile breakpoints.

Building for Different Channels

The build system supports different release channels that automatically select the appropriate OpenCode SDK version:

• Production builds (OPENCODE_CHANNEL=latest): Uses stable SDK from npm (^0.15.14)
• Dev/Preview builds (OPENCODE_CHANNEL=dev or preview): Uses latest dev branch from GitHub for unreleased features

# Build with stable SDK (production)
OPENCODE_CHANNEL=latest bun run build:npm

# Build with dev SDK (includes unreleased MCP features)
OPENCODE_CHANNEL=dev bun run build:npm

The SDK version is automatically set during the build process in script/build-npm.ts.

Security Considerations

This application is designed for local development and does not include built-in authentication. When exposing it outside your local network:

1. Never expose directly to the internet without authentication
2. Use a reverse proxy with authentication like Cloudflare Access
3. Recommended setup: Cloudflare Tunnel + Cloudflare Access for secure, authenticated access
4. Network isolation: Keep it within your firewall when possible
5. Use VPN for remote access instead of direct exposure

Example Cloudflare Tunnel setup:

# Install cloudflared
brew install cloudflared  # macOS
# Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

# Create a tunnel with Access protection
cloudflared tunnel --url http://localhost:3000

Reverse Proxy Configuration

When using reverse proxies like Cloudflare Access, Nginx, or Apache:

1. CORS Headers: The server automatically adds CORS headers when accessed via reverse proxy
2. Virtual Endpoints: Development endpoints (@react-refresh, @vite-plugin-pwa/pwa-entry-point-loaded) return empty responses in production
3. PWA Assets: Use relative URLs by setting VITE_PWA_ASSETS_URL="" when building
4. Base Path: Set VITE_BASE_PATH="/your-path" if hosting under a subdirectory

Example production build for reverse proxy:

VITE_PWA_ASSETS_URL="" VITE_BASE_PATH="" bun run build

Contributing

Follow the shared contributor handbook in AGENTS.md. Before opening a PR, run lint + typecheck, describe UI-visible changes, and flag any server-function updates.