opencode Docker

Docker image for running OpenCode as a headless HTTP server.

What is OpenCode?

OpenCode is an open source AI coding agent available as a terminal interface, desktop app, or IDE extension. This image ships OpenCode 2 and runs it in server mode (opencode serve), exposing an HTTP API and web UI that clients can connect to.

Pull

docker pull jcabillot/opencode

The image is rebuilt and pushed to Docker Hub automatically every night by the Gitea Actions pipeline.

Build locally

docker build -t opencode .

Run

The entrypoint is the opencode binary; pass serve to start the headless server:

docker run -it -p 4096:4096 jcabillot/opencode serve

The server listens on 127.0.0.1:4096 by default. To expose it on all interfaces:

docker run -it -p 4096:4096 jcabillot/opencode serve --hostname 0.0.0.0

Mount a project

docker run -it -p 4096:4096 \
  -v $(pwd):/home/opencode/project \
  jcabillot/opencode serve --hostname 0.0.0.0

Secure with a password

docker run -it -p 4096:4096 \
  -e OPENCODE_SERVER_PASSWORD=your-password \
  jcabillot/opencode serve --hostname 0.0.0.0

Authentication uses HTTP basic auth. The username is always opencode; the password is read from OPENCODE_SERVER_PASSWORD (or OPENCODE_PASSWORD). When neither is set, OpenCode 2 generates a random password and prints it to the log at startup — the server is never left unauthenticated.

Troubleshooting helper

The image includes an opencode-attach wrapper in PATH that runs:

opencode --server "${OPENCODE_API_URL}"

Example:

export OPENCODE_SERVER_PASSWORD=your-password
export OPENCODE_API_URL=http://127.0.0.1:4096
opencode-attach

Extra arguments are forwarded to the client, with --server appended to the subcommand:

opencode-attach session list --format json

API

Once running, the server exposes an OpenAPI 3.1 spec at:

http://localhost:4096/openapi.json

The web UI is served at / and is reachable without credentials; every /api/* route requires basic auth.

Key endpoints:

Method	Path	Description
GET	/api/info	Health check and version
GET	/api/session	List sessions
POST	/api/session	Create a session
POST	/api/session/:id/prompt	Send a message
GET	/api/event	Server-sent events stream

See the OpenCode v2 API reference for the full API surface.

Image details

• Base image: node:26-trixie (Debian)
• Install: @opencode/cli (OpenCode 2) via npm global install
• User: dedicated non-root opencode user
• Cluster tooling: kubectl (copied from official registry image)
• Entrypoint: opencode
• Default port: 4096