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 runs it in server mode (opencode serve), exposing an HTTP API that clients can connect to.

Pull

docker pull jcabillot/opencode

The image is rebuilt and pushed to Docker Hub automatically every night via the Jenkins pipeline.

Build locally

docker build -t opencode .

Run

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

By default the server listens on 127.0.0.1:4096. To expose it on all interfaces:

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

Mount a project

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

Secure with a password

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

Authentication uses HTTP basic auth. The default username is opencode, override it with OPENCODE_SERVER_USERNAME.

Troubleshooting helper

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

opencode attach -p "${OPENCODE_SERVER_PASSWORD}" "${OPENCODE_API_URL}"

Example:

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

API

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

http://localhost:4096/doc

Key endpoints:

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

See the OpenCode server docs for the full API reference.

Image details

Base image: node:24 (Debian)
Install: opencode-ai via npm global install
User: dedicated non-root opencode user
Entrypoint: opencode serve
Default port: 4096

2.2 KiB Raw Blame History