opencode/AGENTS.md

AGENTS.md

Project overview

This repository builds and publishes a Docker image for OpenCode, the open source AI coding agent. The image runs OpenCode in headless server mode (opencode serve) and is automatically rebuilt and pushed to Docker Hub (jcabillot/opencode) every night by a Jenkins pipeline.

Repository structure

.
├── Dockerfile      # Image definition
├── Jenkinsfile     # CI/CD pipeline (nightly build + Docker Hub push)
├── opencode-attach # Helper script for attaching to a running server
└── README.md       # Usage documentation

Dockerfile conventions

• Base image: node:24 — Debian-based Node.js image (not Alpine, needed for apt packages).
• Install: npm i -g opencode-ai n2-soul@<version> — installs OpenCode and Soul globally.
• Version check: RUN opencode --version after install to validate the build and record the installed version in build logs.
• Dedicated user: a non-root opencode user and group are created with groupadd/useradd (UID/GID 1000). All runtime steps run as this user.
• Cluster tooling: kubectl is copied from the official registry.k8s.io/kubectl image (multi-stage COPY).
• Entrypoint: ["opencode"] — arguments are passed at runtime (e.g. serve).

Jenkinsfile conventions

• The pipeline runs on a @midnight cron trigger for nightly rebuilds.
• Build uses --no-cache --pull to always fetch the latest base image and package version.
• Docker Hub credentials are stored under the dockerhub_jcabillot Jenkins credential ID.
• The image is published as jcabillot/opencode (no explicit tag = latest).

Useful commands

# Build the image locally
docker build -t opencode .

# Run the server on all interfaces
docker run -it -p 4096:4096 opencode --hostname 0.0.0.0

# Run with a project mounted
docker run -it -p 4096:4096 \
  -v $(pwd):/home/opencode/project \
  opencode --hostname 0.0.0.0

# Protect with a password
docker run -it -p 4096:4096 \
  -e OPENCODE_SERVER_PASSWORD=secret \
  opencode --hostname 0.0.0.0

opencode serve options

Flag	Default	Description
--port	4096	Port to listen on
--hostname	127.0.0.1	Hostname to bind
--mdns	false	Enable mDNS discovery
--cors	[]	Additional allowed browser origins

Environment variables

Variable	Description
OPENCODE_SERVER_PASSWORD	Enables HTTP basic auth
OPENCODE_SERVER_USERNAME	Overrides the default username (opencode)