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

## Pull

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

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

## Build locally

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

## Run

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

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

### Mount a project

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

### Secure with a password

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

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

Example:

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

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

Quick check inside the container:

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