A hardened image that runs the OpenCode server with the tools an agent needs. Connect the desktop app, the mobile app, the web UI or the terminal to it, and your sessions and tools keep running on the server while your laptop is closed.
Important
peakimages/opencode is currently v0 and subject to breaking changes prior to v1.0.0. Pin to a specific version like peakimages/opencode:2.3.0-v0.1.0 to avoid breaking changes.
The OpenCode server runs the agent and its shell commands, so the image around it decides how much a mistake costs. This image compiles OpenCode from the release tag, runs it unprivileged and brings the tools an agent needs, with mise for every other one.
- ✅ Secure by Default: Runs as unprivileged user
65532onscratch, withoutsudo, a system package manager or setuid files, read-only root filesystem supported - ✅ Built From Source: Compiled from the release tag with the same build script as the OpenCode releases, without network access during the compilation
- ✅ Verified Source: The release tag must point to the pinned commit and every npm package must match the lockfile before each compilation
- ✅ Patched Dependencies: An npm package with a known vulnerability is raised before OpenCode releases the update, see PATCHES.md
- ✅ Batteries Included:
bash, GNU tools,git,gh,ripgrep,curl,jq,make,gccand an SSH client - ✅ Tools on Demand: mise installs languages and CLIs into the home volume without root, and they are kept across image updates
- ✅ Modern Architecture: Native health check,
tiniinit, OCI labels, reproducible builds, provenance and SBOM attestations - ✅ Always Current: GitHub is checked twice a day and new OpenCode releases become new images
- ✅ Multi-Architecture: Builds for
linux/amd64andlinux/arm64 - ✅ Tested: Every release is tested on both platforms before it is published
To see a comparison of this image with other popular OpenCode Docker images, see docs/comparison.md.
OpenCode is a client and a server. The server holds the projects (git repositories), the sessions and the provider keys and runs the agent with its shell commands, the clients show it. This container is meant to be used as a server and can be used as a client with the web UI, the desktop app, terminal or the mobile app.
docker pull peakimages/opencode:2.3.0-v0.1.0Note
The layers of the image are compressed with zstd, pulling it needs Docker Engine 23.0 or later.
The server speaks plain HTTP, so put a reverse proxy with HTTPS in front of it:
services:
opencode:
image: peakimages/opencode:2.3.0-v0.1.0
restart: unless-stopped
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
volumes:
- opencode-data:/home/nonroot
caddy:
image: caddy:2.11.9-alpine
restart: unless-stopped
command:
- caddy
- reverse-proxy
- --from=opencode.example.com
- --to=opencode:${OPENCODE_PORT:-4096}
- --header-down=Strict-Transport-Security:max-age=31536000
depends_on:
opencode:
condition: service_healthy
ports:
- 80:80
- 443:443
- 443:443/udp
volumes:
- caddy-data:/data
volumes:
opencode-data:
caddy-data:On Coolify, the OpenCode service uses the Coolify managed reverse proxy. Coolify also generates the domain and a secure password for you.
services:
opencode:
image: peakimages/opencode:2.3.0-v0.1.0
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
environment:
- SERVICE_URL_OPENCODE_4096
- OPENCODE_PASSWORD=${SERVICE_PASSWORD_64_OPENCODE}
volumes:
- opencode-data:/home/nonrootThe web UI, the desktop app and the mobile app sign in with a link or the OpenCode server password:
-
Print a sign-in link and a QR code, the link works once within 5 minutes and signs in for 30 days:
docker compose exec opencode opencode pair --url https://opencode.example.com -
Open the link in a browser or paste it into the desktop app, or scan the QR code with the mobile app.
The terminal UI signs in with the password:
-
Print the OpenCode server password:
docker compose exec opencode opencode service get password -
Connect from your machine with the password:
export OPENCODE_PASSWORD=your-password opencode --server https://opencode.example.com
Warning
Whoever has the password runs shell commands in the container. The server speaks plain HTTP and does not limit failed logins, so only reach it through a reverse proxy with HTTPS or a private network. The agent can read the password and the provider keys, so use keys you can revoke.
The image brings bash, GNU tools, git, gh, ripgrep, curl, jq, make, gcc and an SSH client. mise installs every other tool into the home volume:
- Languages from its core tools such as Node.js, Bun, Go, Rust, Python, Java and Zig,
mise use -g node@24 go rust - Over 1,000 CLIs from its registry such as pnpm, uv, kubectl and terraform,
mise use -g pnpm - The versions a repository pins in
mise.tomlor.tool-versions,mise trust && mise install - A command mise knows installs itself on its first run, so
go testorcargo buildwork out of the box, no configuration needed
All tags follow this pattern:
peakimages/opencode:{{opencode-version}}-v{{image-version}}| Flavor | Variant | Best For | Example |
|---|---|---|---|
| default | runtime |
General-purpose agents | peakimages/opencode:2.3.0-v0.1.0 |
The default is the runtime variant, OpenCode on scratch with the tools above and without a system package manager.
| Tag | Meaning |
|---|---|
2.3.0-v0.1.0 |
Immutable: OpenCode 2.3.0 built as image v0.1.0, never rebuilt |
2.3.0, 2.3, 2 |
Newest release of that OpenCode patch, minor or major version |
latest |
Newest release |
preview |
Newest prerelease, like 2.3.0-v0.2.0-beta.1, until its release replaces it |
| 📦 Registry | 🐳 Image |
|---|---|
| Docker Hub | |
| GitHub Container Registry |
Every variable is optional, set them with -e or the environment section of a docker compose service.
| Variable | Default | Meaning |
|---|---|---|
OPENCODE_PASSWORD |
generated | Password of the server, at least 32 characters. Without one OpenCode generates it on the first start |
OPENCODE_PASSWORD_FILE |
unset | File that holds the password, such as a Docker secret |
OPENCODE_PORT |
4096 |
Port the OpenCode server listens on |
OpenCode reads its own variables, the most important ones on a server:
| Variable | Default | Meaning |
|---|---|---|
ANTHROPIC_API_KEY, OPENAI_API_KEY |
unset | Key of a provider, in place of signing in from a client |
OPENCODE_CONFIG_CONTENT |
unset | Configuration as JSON, such as {"model":"anthropic/claude-opus-5-5"} |
OPENCODE_CONFIG_PROJECT_DISABLE |
unset | 1 ignores the opencode.json, the plugins and the AGENTS.md of a repository, for code you do not trust |
OPENCODE_DISABLE_MODELS_FETCH |
unset | 1 keeps the built-in list of models and fetches no newer one from models.opencode.ai |
HTTPS_PROXY, NO_PROXY |
unset | Proxy for every request of the server, see network |
GH_TOKEN |
unset | Token for gh, git uses it for https://github.com as well |
MISE_GITHUB_TOKEN |
unset | Token mise asks GitHub with, without one GitHub answers 60 requests per hour |
| Path | Holds |
|---|---|
/home/nonroot |
Repositories, sessions and every installed tool. A volume owned by 65532 |
/home/nonroot/.tmp |
Temporary files, TMPDIR. A link to /tmp, or a directory cleared on every start while /tmp is read-only or noexec |
/home/nonroot/.config/opencode/opencode.json |
Your configuration |
/etc/opencode/opencode.json |
System configuration, it outranks every other |
/etc/mise/config.toml |
Settings of mise |
opencode is one program that runs on any Alpine image with libgcc, libstdc++, bash, git and ripgrep. Copy it with its entrypoint and its health check into the image of the toolchain you need:
FROM php:8.5-cli-alpine
RUN apk add --no-cache bash git ripgrep libgcc libstdc++ tini \
&& adduser -D -u 65532 nonroot
COPY --from=peakimages/opencode:2.3.0-v0.1.0 /usr/local/bin/opencode /usr/local/bin/docker-entrypoint.sh /usr/local/bin/healthcheck.sh /usr/local/bin/
USER 65532:65532
WORKDIR /home/nonroot
ENTRYPOINT ["/sbin/tini", "--", "/usr/local/bin/docker-entrypoint.sh"]
HEALTHCHECK CMD ["/usr/local/bin/healthcheck.sh"]Every image carries an SBOM and a provenance attestation.
The SBOM lists the packages of the image, OpenCode, mise and the Alpine packages:
docker buildx imagetools inspect peakimages/opencode:latest --format '{{ json .SBOM }}'The provenance records how the image was built:
docker buildx imagetools inspect peakimages/opencode:latest --format '{{ json .Provenance }}'A scanner lists the same packages, Trivy all but OpenCode and mise:
syft peakimages/opencode:latest
grype peakimages/opencode:latest
trivy image peakimages/opencode:latestEvery OpenCode release becomes a new version of the image. A check for new OpenCode releases runs twice a day.
The image version follows semantic versioning independently of OpenCode. Changes to the image are listed in CHANGELOG.md.
This image is built and published by PeakImages. All third-party product names, logos and trademarks are the property of their respective owners and are used solely for identification. PeakImages claims no interest in those marks, and no affiliation, sponsorship or endorsement is implied.