Docker Setup

July 14, 2026 · View on GitHub

Run OpenCode Chat Bridge with Docker - no Bun or Node.js installation required.

OpenCode Updates

OpenCode is downloaded fresh on each container start, ensuring you always have the latest version. First startup takes ~10 seconds longer.

To persist OpenCode and avoid re-downloading on restart:

docker run ... -v opencode-bin:/root/.opencode ...

To update a persisted installation, remove the volume:

docker volume rm opencode-bin

Quick Start

# Pull the latest image
docker pull lbecchi/opencode-chat-bridge

# Run a connector (example: Discord)
docker run -d \
  --name opencode-discord \
  -e CONNECTOR=discord \
  -e DISCORD_TOKEN=your_bot_token \
  -v opencode-sessions:/data/sessions \
  lbecchi/opencode-chat-bridge

Using Docker Compose (Recommended)

Docker Compose makes it easy to manage multiple connectors and persistent storage.

1. Clone and Configure

git clone https://github.com/ominiverdi/opencode-chat-bridge
cd opencode-chat-bridge
cp .env.example .env

2. Edit `.env` with Your Credentials

# Discord
DISCORD_TOKEN=your_discord_bot_token

# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token

# Matrix
MATRIX_HOMESERVER=https://matrix.org
MATRIX_USER_ID=@yourbot:matrix.org
MATRIX_PASSWORD=your_password

# Mattermost
MATTERMOST_URL=https://mattermost.example.com
MATTERMOST_TOKEN=your_bot_token

# Telegram
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# Optional: restrict to specific Telegram user IDs
# TELEGRAM_ALLOWED_USERS=123456789,987654321
# Optional: skip messages queued while the bot was offline
# TELEGRAM_DROP_PENDING=1

3. Run Connectors

# Run a single connector
docker-compose up discord

# Run multiple connectors
docker-compose up discord slack matrix telegram

# Run in background
docker-compose up -d discord

# View logs
docker-compose logs -f discord

# Stop
docker-compose down

Available Connectors

Connector	Environment Variables
`discord`	`DISCORD_TOKEN`
`slack`	`SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`
`matrix`	`MATRIX_HOMESERVER`, `MATRIX_USER_ID`, `MATRIX_PASSWORD` or `MATRIX_ACCESS_TOKEN`
`whatsapp`	(QR code auth - see below)
`mattermost`	`MATTERMOST_URL`, `MATTERMOST_TOKEN`, `MATTERMOST_TEAM` (optional)
`telegram`	`TELEGRAM_BOT_TOKEN`, `TELEGRAM_ALLOWED_USERS` (optional), `TELEGRAM_DROP_PENDING` (optional), `TELEGRAM_TRIGGER` (optional)

WhatsApp Setup

WhatsApp requires QR code authentication on first run:

# Run interactively to scan QR code
docker-compose run --rm whatsapp

# After linking, run in background
docker-compose up -d whatsapp

The auth session is persisted in the whatsapp-auth volume.

Configuration Files

The bot uses three configuration files. Mount them into the container:

docker run ... \
  -v /path/to/opencode.json:/app/opencode.json:ro \
  -v /path/to/chat-bridge.json:/app/chat-bridge.json:ro \
  -v /path/to/AGENTS.md:/app/AGENTS.md:ro \
  ...

opencode.json

Model and AI provider configuration. See opencode.example.json for reference.

{
  "model": "anthropic/claude-sonnet-4-20250514"
}

chat-bridge.json

Bot settings: trigger prefix, bot name, connector options. See chat-bridge.json.example for reference.

{
  "botName": "mybot",
  "trigger": "!bot",
  "matrix": {
    "enabled": true,
    "homeserver": "https://matrix.org",
    "userId": "{env:MATRIX_USER_ID}",
    "password": "{env:MATRIX_PASSWORD}"
  }
}

Environment variables are substituted using {env:VAR_NAME} syntax.

AGENTS.md

System prompt and instructions for the AI. This file is copied to each session directory.

AI Provider Configuration

Set your API key as an environment variable:

# Anthropic (Claude)
docker run ... -e ANTHROPIC_API_KEY=sk-ant-xxx ...

# OpenAI
docker run ... -e OPENAI_API_KEY=sk-xxx ...

# Google
docker run ... -e GOOGLE_API_KEY=xxx ...

For local LLM servers (llama.cpp, Ollama, etc.), use --network=host to access localhost.

Persistent Storage

Docker volumes store runtime data:

sessions - Conversation history for all connectors
whatsapp-auth - WhatsApp authentication data
opencode - OpenCode binary (optional, avoids re-download on restart)
opencode-data - OpenCode database and settings

Recommended volume mounts:

docker run ... \
  -v opencode-sessions:/data/sessions \
  -v opencode-bin:/root/.opencode \
  -v opencode-data:/root/.local/share/opencode \
  ...

To clear sessions:

docker volume rm opencode-chat-bridge_sessions

Building Locally

# Build the image
docker build -t opencode-chat-bridge .

# Run with local build
docker run -e CONNECTOR=discord -e DISCORD_TOKEN=... opencode-chat-bridge

Image Tags

lbecchi/opencode-chat-bridge:latest - Latest stable release
lbecchi/opencode-chat-bridge:main - Latest main branch
lbecchi/opencode-chat-bridge:0.4.0 - Specific version

Troubleshooting

View Logs

docker-compose logs -f discord
docker logs opencode-discord

Container Won't Start

Check environment variables are set:

docker-compose config

Session Issues

Clear and restart:

docker-compose down
docker volume rm opencode-chat-bridge_sessions
docker-compose up -d discord