### [OpenCode](https://github.com/anomalyco/opencode)

> Handle: `opencode`<br/>
> URL: [http://localhost:34711](http://localhost:34711)

![OpenCode Screenshot](./harbor-opencode.png)

OpenCode is an AI-powered coding assistant that provides a server API, terminal UI, desktop app, and IDE extensions. It supports multiple LLM providers (Anthropic, OpenAI, Google, OpenRouter, etc.), offers advanced agentic workflows with built-in tools (file operations, web search, LSP integration), and enables multi-session management with context awareness.

**Key Features:**
- Server API with OpenAPI documentation at `/doc`
- Terminal UI (TUI) via `opencode attach`
- Multiple LLM provider support (local via Ollama or cloud)
- Built-in tools: file operations, web search, code formatting, LSP integration
- Session management with context compaction
- MCP (Model Context Protocol) server integration
- Plugin system for custom tools and agents
- Workspace-aware file operations

#### Starting

```bash
# Pull the image
harbor pull opencode

# Start the service and open its WebUI in the browser
harbor up opencode --open
```

See [`harbor pull`](./3.-Harbor-CLI-Reference.md#harbor-pull) and [`harbor up`](./3.-Harbor-CLI-Reference.md#harbor-up) for more options.

- Harbor will connect `opencode` to `ollama`, `llamacpp`, `vllm` and other internal inference engines automatically
- Harbor will automatically discover avaialble models and pre-populate them for the `opencode`

#### Usage

##### Server API

Access the OpenAPI documentation at [http://localhost:34711/doc](http://localhost:34711/doc).

The server provides REST and WebSocket endpoints for:
- Session management
- Message streaming
- Agent execution
- Tool invocation

##### Harbor CLI Mount

Start OpenCode with `harbor-cli` when you want agents in the OpenCode container to inspect and manage Harbor services:

```bash
harbor up opencode harbor-cli
```

This mounts the Harbor home directory, Docker socket, `/harbor/harbor_cli_init.sh`, and the local LLM skill file into the OpenCode container. The image includes the Docker CLI and Compose plugin; run `sh /harbor/harbor_cli_init.sh` inside the container to place `harbor` on `PATH`.

##### CLI Subcommand

Harbor provides an [`opencode`](./3.-Harbor-CLI-Reference.md#service-specific-commands) subcommand to manage workspaces:

```bash
# Add a workspace (updates HARBOR_OPENCODE_WORKSPACES)
harbor opencode workspaces add ~/projects/my-app

# Remove a workspace
harbor opencode workspaces rm ~/projects/my-app

# List configured workspaces
harbor opencode workspaces ls
```

##### Basic Authentication

Optional basic auth can be configured for the server:

```bash
harbor config set opencode.username "myuser"
harbor config set opencode.password "mypassword"
```

After setting credentials, restart the service for changes to take effect. See [`harbor config`](./3.-Harbor-CLI-Reference.md#harbor-config) and [`harbor restart`](./3.-Harbor-CLI-Reference.md#harbor-restart) for details.

#### Configuration

Following options can be set via [`harbor config`](./3.-Harbor-CLI-Reference.md#harbor-config):

```bash
# Main server port
HARBOR_OPENCODE_HOST_PORT          34711

# Persistent storage
HARBOR_OPENCODE_DATA               ./opencode/data
HARBOR_OPENCODE_CONFIG             ./opencode/config

# Basic authentication (optional)
HARBOR_OPENCODE_USERNAME           ""
HARBOR_OPENCODE_PASSWORD           ""

# Workspace mounts (semicolon-separated paths)
HARBOR_OPENCODE_WORKSPACES         ""
```

#### Volumes

- `HARBOR_OPENCODE_DATA` (`./opencode/data`) → `/root/.local/share/opencode` - Session data, logs, and auth tokens
- `HARBOR_OPENCODE_CONFIG` (`./opencode/config`) → `/root/.config/opencode` - Configuration files
- Workspace directories (configured via `HARBOR_OPENCODE_WORKSPACES`) → `/root/<name>` - Project files for coding tasks

#### Workspace Management

OpenCode supports mounting multiple workspace directories for file operations.

##### Manual Configuration

Edit the `HARBOR_OPENCODE_WORKSPACES` variable in your profile using [`harbor config`](./3.-Harbor-CLI-Reference.md#harbor-config):

```bash
# Semicolon-separated list of paths
harbor config set opencode.workspaces "~/projects/app1;~/projects/app2;~/code/lib"
```

Workspace paths can be:
- Absolute paths: `/home/user/projects/my-app`
- Relative paths: `./projects/my-app` (relative to Harbor home)
- Home-relative: `~/projects/my-app`

Each workspace is mounted as `/root/<basename>` in the container.

##### Using CLI Subcommand

The `harbor opencode workspaces` command provides a convenient interface:

```bash
# Add workspace
harbor opencode workspaces add ~/projects/my-app

# Remove workspace
harbor opencode workspaces rm ~/projects/my-app

# List workspaces
harbor opencode workspaces ls
```

#### Backend Integration

OpenCode supports automatic model discovery from Harbor inference backends. When starting OpenCode alongside compatible backends, the service automatically detects available models and configures them for use.

##### Supported Backends

The following Harbor backends are supported for auto-discovery:

- `ollama` - Ollama inference server
- `llamacpp` - llama.cpp server
- `vllm` - vLLM inference engine
- `tabbyapi` - TabbyAPI (ExLlamaV2)
- `mistralrs` - mistral.rs inference
- `sglang` - SGLang inference
- `lmdeploy` - LMDeploy inference
- `unsloth-studio` - [Unsloth Studio](./2.3.83-Satellite-Unsloth-Studio.md) (the cross-integration mounts the bootstrapped API key so the discovered provider authenticates correctly — see [Use as an inference backend for other Harbor services](./2.3.83-Satellite-Unsloth-Studio.md#use-as-an-inference-backend-for-other-harbor-services))

##### Model Auto-Discovery

When OpenCode starts with one or more compatible backends, the entrypoint script:

1. Waits for each backend to become available (30 second timeout per backend)
2. Queries the `/v1/models` endpoint on each backend
3. Generates an `opencode.json` configuration with discovered providers and models
4. The backends appear as "BackendName (Harbor)" in the model selector

This happens at container startup. Models added to backends after startup require a restart:

```bash
harbor restart opencode
```

##### Usage

Start OpenCode with one or more backends:

```bash
# With Ollama
harbor up ollama opencode

# With llama.cpp
harbor up llamacpp opencode

# With multiple backends
harbor up ollama vllm opencode
```

See [`harbor up`](./3.-Harbor-CLI-Reference.md#harbor-up) for more startup options.

##### Manual Configuration

If auto-discovery is not desired, or for additional providers (Anthropic, OpenAI, etc.), configure models manually in `opencode.json` located in `HARBOR_OPENCODE_CONFIG`.

Configure via environment variables:
- `OPENCODE_AUTO_SHARE` - Auto-share sessions
- `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` - Enable experimental model support

#### Environment Variables

OpenCode supports extensive configuration via environment variables:

```bash
# Configuration paths
OPENCODE_CONFIG                    # Path to custom opencode.json
OPENCODE_CONFIG_DIR                # Custom config directory
OPENCODE_CONFIG_CONTENT            # Inline JSON configuration

# Feature flags
OPENCODE_AUTO_SHARE                # Auto-share sessions
OPENCODE_DISABLE_AUTOUPDATE        # Disable update checks
OPENCODE_DISABLE_PRUNE             # Disable data pruning
OPENCODE_DISABLE_DEFAULT_PLUGINS   # Disable default plugins
OPENCODE_DISABLE_LSP_DOWNLOAD      # Disable LSP server downloads
OPENCODE_ENABLE_EXPERIMENTAL_MODELS # Enable experimental models
OPENCODE_DISABLE_AUTOCOMPACT       # Disable context compaction
OPENCODE_ENABLE_EXA                # Enable Exa web search

# Authentication
OPENCODE_SERVER_USERNAME           # Server basic auth username
OPENCODE_SERVER_PASSWORD           # Server basic auth password

# Permissions (inline JSON)
OPENCODE_PERMISSION                # Custom permission configuration
```

Set these via the service's `override.env` file:

```bash
# Edit services/opencode/override.env
OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true
OPENCODE_AUTO_SHARE=true
```

#### Notes

- Server listens on `0.0.0.0:4096` inside the container (mapped to host port 34711)
- Session data and auth tokens are persisted in `HARBOR_OPENCODE_DATA`
- Configuration files are persisted in `HARBOR_OPENCODE_CONFIG`
- OpenAPI documentation available at [http://localhost:34711/doc](http://localhost:34711/doc)
- WebSocket endpoint for message streaming: `ws://localhost:34711/api/sessions/{session_id}/stream`
- Requires workspace mounts for file operations (use `harbor opencode workspace add`)

#### Troubleshooting

See the [Harbor Troubleshooting Guide](./1.-Harbor-User-Guide.md#troubleshooting) for general help.

##### Common Issues

**Service won't start:**
- Check logs: [`harbor logs opencode`](./3.-Harbor-CLI-Reference.md#harbor-logs)
- Verify port 34711 is not in use: `lsof -i :34711`

**Can't access files in workspace:**
- Ensure workspace is added via [`harbor opencode workspaces add`](./3.-Harbor-CLI-Reference.md#service-specific-commands)
- Verify workspace path exists and is readable
- Check volume mounts: `docker inspect harbor.opencode`

**TUI won't attach:**
- Ensure server is running: [`harbor ps opencode`](./3.-Harbor-CLI-Reference.md#harbor-ps)
- Check container logs for errors: [`harbor logs opencode`](./3.-Harbor-CLI-Reference.md#harbor-logs)

**Authentication not working:**
- Verify credentials are set: [`harbor config get opencode.username`](./3.-Harbor-CLI-Reference.md#harbor-config)
- Restart service after changing credentials: [`harbor restart opencode`](./3.-Harbor-CLI-Reference.md#harbor-restart)
