OpenCode Studio

English | 简体中文 | Español | हिंदी | العربية | Português (Brasil) | Français

OpenCode Studio for focused OpenCode workflows.
One workspace for chat, files, terminal, Git, and settings.
Built for fast local usage and reliable always-on deployment.

Get Release · Technical Docs · Service Install · Language Index · Issue Tracker

Note: This is a community project and is not built by the OpenCode team and is not affiliated with them. Upstream OpenCode: anomalyco/opencode

Language Support

OpenCode Studio frontend i18n and top-level docs support the following locales:

• zh-CN: Simplified Chinese
• en-US: English
• es-ES: Spanish (Spain)
• hi-IN: Hindi (India)
• ar-SA: Arabic (Saudi Arabia)
• pt-BR: Portuguese (Brazil)
• fr-FR: French (France)

See docs/i18n/README.md for the language matrix and cross-links.

Contents

• Language Support
• Why OpenCode Studio
• Recommended Plugin: Managed Web Previews
• UI Preview
• Quick Start (2 minutes)
• Installation Details
• After Install
• Troubleshooting
• Service Management
• Technical Details and Parameters
• License

Why OpenCode Studio

• Unified workflow across chat, files, terminal, and Git in one workspace.
• OpenCode event-stream bridge with real-time updates and resume behavior.
• Performance-focused proxy path with payload pruning and response shaping for long sessions.
• Pagination-first data access (offset/limit) to reduce initial load pressure.
• Lazy-loading strategy so heavier content is fetched and rendered on demand.
• Studio-only plugin UI system: discovers plugins via opencode.json, loads studio.manifest.json, and exposes actions in UI.
• Local-first plus ops-friendly deployment: package install for desktop use, or managed service install for always-on usage.

Recommended Plugin: Managed Web Previews

If you do frontend work in OpenCode Studio, install opencode-web-preview in OpenCode. This plugin is built specifically for Studio and cannot be used standalone: Studio owns preview session storage, proxy routing, and preview lifecycle, while the plugin lets the agent start, stop, restart, and inspect local dev servers with Studio-compatible preview links.

• npm package: opencode-web-preview
• Plugin repo: canxin121/opencode-web-preview

Add it to your OpenCode config file opencode.json:

• Unix/macOS: ~/.config/opencode/opencode.json
• Windows: %USERPROFILE%\\.config\\opencode\\opencode.json (for example: C:\\Users\\<your-user>\\.config\\opencode\\opencode.json)

{
  "plugin": ["opencode-web-preview"]
}

OpenCode installs npm plugins automatically when the session starts.

Example prompt:

Use web_preview_helper to start a managed preview for this frontend workspace.

UI Preview

• Chat view: sessions, streaming messages, and tool traces.
• Files view: workspace browsing, editing, and search/replace.
• Terminal view: integrated PTY session for command workflows.
• Git view: status, diff, branch/worktree helpers.
• Settings view: OpenCode config layers plus Studio-local settings.

Quick Start (2 minutes)

1. Install OpenCode CLI first (choose one method).

# macOS / Linux (official install script)
curl -fsSL https://opencode.ai/install | bash

# macOS / Linux (Homebrew)
brew install anomalyco/tap/opencode

# Windows (Scoop)
scoop install opencode

# Windows (Chocolatey)
choco install opencode

# Any platform with Bun
bun add -g opencode-ai@latest

2. Verify installation.

opencode --version

3. Choose an installation path.

Scenario	Recommended path	What you get
Local desktop usage	Package install	Native desktop app with bundled backend service
Always-on host / server-like environment	Service install	Managed service via systemd, launchd, or Windows SCM

4. Open in browser:

• Frontend-enabled install: http://127.0.0.1:3210
• API-only install: http://127.0.0.1:3210/health

Installation Details

Option 1: Package Install (Desktop App)

Best for local desktop usage.

1. Open GitHub Releases
2. Download your platform package:
   • Windows: .msi / .exe
   • macOS: .dmg
   • Linux: .AppImage / .deb / .rpm
3. Install and launch the app; the bundled backend service starts automatically.

Option 2: Service Install

Best for always-on hosts, server-like usage, or environments managed by systemd / launchd / sc (Windows uses an NSSM service wrapper under SCM).

On Windows, installer scripts register two services:

• OpenCodeStudio-OpenCode (managed opencode serve on port 16000)
• OpenCodeStudio (web/API service depending on OpenCodeStudio-OpenCode)

Unix (Linux/macOS):

# Service install with bundled UI
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/install-service.sh | bash -s -- --with-frontend

# Service install API-only (no bundled UI)
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/install-service.sh | bash

# Service install with custom bind host/port/password
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/install-service.sh | bash -s -- --with-frontend --host 0.0.0.0 --port 3210 --ui-password "change-me"

Windows PowerShell (run as Administrator):

# Service install with bundled UI
iex "& { $(irm https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/install-service.ps1) } -WithFrontend"

# Service install API-only (no bundled UI)
iex "& { $(irm https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/install-service.ps1) }"

# Service install with custom bind host/port/password
iex "& { $(irm https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/install-service.ps1) } -WithFrontend -Host 0.0.0.0 -Port 3210 -UiPassword 'change-me'"

After Install

Open in browser

• Default service address is http://127.0.0.1:3210 (from host + port in config).
• Default generated auth password is empty (ui_password = ""), so password login is disabled.
• If installed with frontend, open http://127.0.0.1:3210 directly.
• If installed API-only, use http://127.0.0.1:3210/health to verify service health.
• To enable UI after API-only install, set ui_dir in opencode-studio.toml to a valid dist directory, or reinstall with --with-frontend / -WithFrontend.
• For remote machine access, change host to 0.0.0.0, restart service, then visit http://<server-ip>:3210.

Update configuration

For service install, the installer generates opencode-studio.toml:

• Unix: ~/opencode-studio/opencode-studio.toml
• Windows: %USERPROFILE%\\opencode-studio\\opencode-studio.toml

Edit key values under [backend]:

[backend]
host = "127.0.0.1"
port = 3210
ui_password = ""
skip_opencode_start = false
opencode_host = "127.0.0.1"
# opencode_port = 16000
# ui_dir = "/absolute/path/to/web/dist"

Windows service installs default to skip_opencode_start = true so the service can start reliably under SCM. The installer also writes opencode_port = 16000 and manages a companion OpenCodeStudio-OpenCode service.

Apply changes by restarting the service:

• Linux user service: systemctl --user restart opencode-studio
• Linux system service: sudo systemctl restart opencode-studio
• Windows service: sc stop OpenCodeStudio then sc start OpenCodeStudio

For package install, runtime config is stored in the app data directory. Use the tray menu action to open the config file directly.

Troubleshooting

macOS: app is damaged and can't be opened

This usually means macOS Gatekeeper is blocking a downloaded (non-notarized) build.

1. Open the .dmg and drag OpenCode Studio.app into /Applications.
2. In Finder, open /Applications, right-click the app -> Open -> confirm.
3. If it still shows the "damaged" dialog, remove the quarantine flag:

xattr -dr com.apple.quarantine "/Applications/OpenCode Studio.app"

Then launch the app again.

Service Management

The commands below apply to the service-install path.

Linux (default user-mode install)

# status / start / stop / restart
systemctl --user status opencode-studio
systemctl --user start opencode-studio
systemctl --user stop opencode-studio
systemctl --user restart opencode-studio

# autostart on login
systemctl --user enable opencode-studio
systemctl --user disable opencode-studio

# uninstall service unit
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.sh | bash

# uninstall service unit + installed files
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.sh | bash -s -- --remove-install-dir

Linux (--mode system install)

# status / start / stop / restart
sudo systemctl status opencode-studio
sudo systemctl start opencode-studio
sudo systemctl stop opencode-studio
sudo systemctl restart opencode-studio

# autostart on boot
sudo systemctl enable opencode-studio
sudo systemctl disable opencode-studio

# uninstall service unit
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.sh | bash

# uninstall service unit + installed files
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.sh | bash -s -- --remove-install-dir

macOS (launchd, label: cn.cxits.opencode-studio)

# status
launchctl list | grep opencode

# restart
launchctl kickstart -k gui/$(id -u)/cn.cxits.opencode-studio

# stop autostart (unload agent)
launchctl unload "$HOME/Library/LaunchAgents/cn.cxits.opencode-studio.plist"

# enable autostart again (load agent)
launchctl load "$HOME/Library/LaunchAgents/cn.cxits.opencode-studio.plist"

# uninstall service agent
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.sh | bash

# uninstall service agent + installed files
curl -fsSL https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.sh | bash -s -- --remove-install-dir

Windows (services: OpenCodeStudio-OpenCode, OpenCodeStudio)

# status / start / stop / restart
sc query OpenCodeStudio-OpenCode
sc query OpenCodeStudio
sc start OpenCodeStudio-OpenCode
sc start OpenCodeStudio
sc stop OpenCodeStudio
sc stop OpenCodeStudio-OpenCode
sc stop OpenCodeStudio; sc start OpenCodeStudio

# autostart
sc config OpenCodeStudio-OpenCode start= auto
sc config OpenCodeStudio start= auto

# disable autostart
sc config OpenCodeStudio start= demand
sc config OpenCodeStudio-OpenCode start= demand

# uninstall services
iex "& { $(irm https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.ps1) }"

# uninstall services + installed files
iex "& { $(irm https://raw.githubusercontent.com/canxin121/opencode-studio/master/scripts/uninstall-service.ps1) } -RemoveInstallDir"

Technical Details and Parameters

All technical details, configuration parameters, and developer-centric references are consolidated in:

• docs/technical-reference.md

Related docs:

• docs/service.md (service install/uninstall details)
• docs/packaging.md (package artifacts and build outputs)
• desktop/README.md (desktop packaging notes)
• docs/opencode-studio.toml.example (runtime config example)
• docs/backend-accel-parity-review.md (backend acceleration parity review)
• docs/i18n/README.md (language matrix)
• SECURITY.md (security notes)
• CONTRIBUTING.md (contribution guide)

License

MIT. See LICENSE.