# AGENTS.md

## Project overview

This repository builds and publishes a Docker image for [OpenCode](https://opencode.ai), 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)
└── README.md       # Usage documentation
```

## Dockerfile conventions

- **Base image**: `node:24-alpine` — use the latest Node.js LTS Alpine image.
- **Install**: `npm i -g opencode-ai` — installs OpenCode 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 `addgroup`/`adduser`. All runtime steps run as this user.
- **Entrypoint**: `["opencode", "serve"]` — the container always starts the HTTP server.

## 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

```bash
# 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`) |