OpenCode Docker Compose

A secure-by-default, persistent, health-checked Docker Compose deployment for the OpenCode web interface.

This is an independent community project. It is not affiliated with, endorsed by, or maintained by the OpenCode project or Anomaly.

Why this project exists

OpenCode now publishes an official multi-architecture container image. This repository builds on that image and adds the deployment defaults needed for a long-running browser-based installation:

• HTTP Basic authentication is required before the container starts.
• The host port binds to 127.0.0.1 by default.
• OpenCode runs as an unprivileged user with all Linux capabilities dropped.
• Credentials, configuration, sessions, logs, state, and cache persist in one named volume.
• A separate workspace mount gives OpenCode access only to the code you select.
• An authenticated health check verifies the OpenCode API.
• Local validation and smoke-test scripts cover the entrypoint, Compose configuration, and running container.

Quick start

Requirements: Docker Engine or Docker Desktop with Docker Compose.

git clone https://github.com/andersennl/opencode-docker-compose.git
cd opencode-docker-compose
cp .env.example .env
mkdir -p workspace

Edit .env and set OPENCODE_SERVER_PASSWORD to a strong, unique value before starting the container. You can generate one with:

openssl rand -hex 32

Then start the service:

docker compose up -d

Open http://127.0.0.1:4096 and sign in with the configured username and password. The default username is opencode.

To stop the service without deleting its persisted state:

docker compose down

Configuration

Variable	Default	Purpose
OPENCODE_SERVER_PASSWORD	none; required	Password for HTTP Basic authentication
OPENCODE_SERVER_USERNAME	opencode	Username for HTTP Basic authentication
OPENCODE_BIND_ADDRESS	127.0.0.1	Host interface that publishes the web port
OPENCODE_PORT	4096	Published host port
OPENCODE_WORKSPACE	./workspace	Host directory exposed to OpenCode

Provider credentials can be configured through OpenCode after startup. They are stored in the persistent data volume; they are not baked into this image.

Persistence

The opencode-data volume is mounted at /appdata. OpenCode's XDG paths are redirected into it:

Data	Container path
Credentials, sessions, and logs	/appdata/share/opencode
Global configuration	/appdata/config/opencode
State	/appdata/state/opencode
Cache	/appdata/cache/opencode

The source directory configured by OPENCODE_WORKSPACE is mounted separately at /workspace. The container runs as UID/GID 1000; on Linux, ensure that this user can read and write the selected workspace.

Security

OpenCode can read, modify, and execute code inside the mounted workspace. Only mount directories you intend to expose.

The default bind address keeps the service on the local machine. Do not change it to 0.0.0.0 or expose it to the internet without a strong password and a TLS-enabled reverse proxy. Never commit .env or provider credentials.

Updating and local builds

The versioned FROM line at the top of the Dockerfile is the single source of truth for the official OpenCode image version. Review upstream releases and run the validation and smoke tests before updating that reference.

Build and start the local source instead of pulling the published image:

docker compose up -d --build

Run the repository validation and container smoke test:

./tests/validate.sh
./tests/smoke.sh

validate.sh does not require a running Docker daemon. smoke.sh builds and starts the image and therefore does.

Roadmap

• Publish versioned repository releases in addition to latest and commit tags.
• Add a documented TLS reverse-proxy example.
• Add tested backup and restore instructions for /appdata.
• Add compatibility tests for new major OpenCode releases before updating the default version.

Contributing

Bug reports and focused pull requests are welcome. Read CONTRIBUTING.md before submitting a change.

License

This repository is available under the MIT License. OpenCode itself is distributed under its own license.