opencode/README.md

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

Podman rootless (ready-to-use)

The image now includes Podman configured for rootless usage with the opencode user (/etc/subuid, /etc/subgid, fuse-overlayfs, slirp4netns).

When running this image, add runtime options required by Podman-in-container:

docker run -it -p 4096:4096 \
  --security-opt seccomp=unconfined \
  --device /dev/fuse \
  jcabillot/opencode

Quick check inside the container:

podman info

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
• Container tooling: Podman rootless (podman, uidmap, slirp4netns, fuse-overlayfs)
• Entrypoint: opencode serve
• Default port: 4096