opencode/README.md

# opencode Docker

Docker image for running [OpenCode](https://opencode.ai) 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

```bash
docker pull jcabillot/opencode
```

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

## Build locally

```bash
docker build -t opencode .
```

## Run

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

```bash
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:

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

### Mount a project

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

### Secure with a password

```bash
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:

```bash
opencode --server "${OPENCODE_API_URL}"
```

Example:

```bash
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:

```bash
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](https://opencode.ai/v2/docs/api/) 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`