opencode-devbox/DOCKER_HUB.md

# opencode-devbox — Docker Hub

Portable AI developer environment for [opencode](https://opencode.ai). Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.

## Quick Start

```bash
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e OPENCODE_PROVIDER=anthropic \
  -e GIT_USER_NAME="Your Name" \
  -e GIT_USER_EMAIL="you@example.com" \
  -v ~/projects:/workspace \
  -v ~/.ssh:/home/developer/.ssh:ro \
  joakimp/opencode-devbox:latest
```

This drops you straight into opencode with your project mounted at `/workspace`.

## Interactive Shell

To get a shell first (useful for AWS SSO login or running other commands):

```bash
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e OPENCODE_PROVIDER=anthropic \
  -v ~/projects:/workspace \
  -v ~/.ssh:/home/developer/.ssh:ro \
  joakimp/opencode-devbox:latest bash
```

Then run `opencode` when ready.

## Running Multiple Shells

Once opencode is running it takes over the terminal. To have a separate shell for `aws`, `git`, or other commands, run the container in the background and attach multiple times:

```bash
# Start in background
docker run -d --name devbox \
  -e ANTHROPIC_API_KEY=your-key \
  -e OPENCODE_PROVIDER=anthropic \
  -v ~/projects:/workspace \
  -v ~/.ssh:/home/developer/.ssh:ro \
  joakimp/opencode-devbox:latest sleep infinity

# Shell 1: run opencode
docker exec -it devbox opencode

# Shell 2 (separate terminal): aws, git, etc.
docker exec -it devbox bash

# When done
docker rm -f devbox
```

With docker-compose this is simpler:

```bash
docker compose up -d
docker compose exec devbox opencode     # terminal 1
docker compose exec devbox bash         # terminal 2
```

## Environment Variables

### Provider Configuration

| Variable | Description | Default |
|---|---|---|
| `OPENCODE_PROVIDER` | LLM provider (`anthropic`, `openai`, `amazon-bedrock`) | `anthropic` |
| `OPENCODE_MODEL` | Model override | Provider default |

### API Keys

Set the key matching your provider:

| Variable | Provider |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic |
| `OPENAI_API_KEY` | OpenAI |
| `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (static creds) |

### AWS Bedrock

| Variable | Description | Default |
|---|---|---|
| `AWS_REGION` | AWS region | `us-east-1` |
| `AWS_PROFILE` | AWS profile name | `default` |

For SSO authentication, start with `bash` and run:

```bash
aws sso login --sso-session <your-session> --use-device-code
opencode
```

### Git

| Variable | Description |
|---|---|
| `GIT_USER_NAME` | Git commit author name |
| `GIT_USER_EMAIL` | Git commit author email |

### User ID Mapping

The container runs as user `developer` (UID 1000 by default). If your host user has a different UID, file permission mismatches can occur on mounted volumes.

The entrypoint automatically detects the owner of `/workspace` and adjusts the container user's UID/GID to match. You can also set it explicitly:

| Variable | Description | Default |
|---|---|---|
| `USER_UID` | Container user UID | Auto-detect from `/workspace` owner |
| `USER_GID` | Container user GID | Auto-detect from `/workspace` owner |

```bash
docker run -it --rm \
  -e USER_UID=$(id -u) \
  -e USER_GID=$(id -g) \
  -v ~/projects:/workspace \
  joakimp/opencode-devbox:latest
```

## Data Storage and Persistence

Understanding what survives container restarts and what doesn't:

| Path in container | Source | Survives restart? | Contains |
|---|---|---|---|
| `/workspace` | Host bind mount | ✅ Yes — lives on host | Your project files |
| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
| `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No — regenerated each start | Provider config, MCP server definitions |
| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes — lives on host | AWS credentials/SSO cache |

### Key points

- **Project files** (`/workspace`) are always safe — they're your host filesystem.
- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start. It only sets provider and model — no MCP servers. To persist MCP server config, mount your own config file (see Custom opencode Config below).
- **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
- **AWS SSO tokens** are stored inside the container and lost on restart. Re-run `aws sso login` after restarting.

### Persisting opencode data

Add a named volume to keep session history and memory between runs:

```bash
docker run -it --rm \
  -v opencode-data:/home/developer/.local/share/opencode \
  ... \
  joakimp/opencode-devbox:latest
```

## Custom opencode Config

For full control (MCP servers, custom models, keybindings), mount your own config:

```bash
docker run -it --rm \
  -v ./my-opencode.json:/home/developer/.config/opencode/opencode.json:ro \
  ... \
  joakimp/opencode-devbox:latest
```

When a config file is mounted, the `OPENCODE_PROVIDER` auto-config is skipped.

## Using docker-compose

Create a `docker-compose.yml` and a `.env` file in the same directory:

```bash
mkdir opencode-devbox && cd opencode-devbox
```

`.env` — your secrets and settings (never commit this):

```bash
ANTHROPIC_API_KEY=sk-ant-...
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com
```

`docker-compose.yml`:

```yaml
services:
  devbox:
    image: joakimp/opencode-devbox:latest
    stdin_open: true
    tty: true
    environment:
      - TERM=xterm-256color
      - OPENCODE_PROVIDER=anthropic
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GIT_USER_NAME=${GIT_USER_NAME}
      - GIT_USER_EMAIL=${GIT_USER_EMAIL}
    volumes:
      - ~/projects:/workspace
      - ~/.ssh:/home/developer/.ssh:ro
      - devbox-data:/home/developer/.local/share/opencode
      # Optional: mount your own opencode config (MCP servers, custom models, etc.)
      # - ./opencode.json:/home/developer/.config/opencode/opencode.json:ro
      # Optional: mount opencode skills from host
      # - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
      # - ~/.agents/skills:/home/developer/.agents/skills:ro
      # Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
      # - ~/.aws:/home/developer/.aws

volumes:
  devbox-data:
```

Docker Compose automatically loads `.env` from the same directory as the compose file. The `${VAR}` references are substituted with values from `.env`.

Then:

```bash
docker compose run --rm devbox        # direct to opencode
docker compose run --rm devbox bash   # interactive shell
```

## What's Included

- **Debian bookworm-slim** — glibc, full terminal/PTY support
- **opencode** — AI coding assistant
- **Node.js 22** — for npx-based MCP servers
- **AWS CLI v2** — SSO and Bedrock authentication
- **Dev tools** — git, git-lfs, ssh, ripgrep, fd, fzf, jq, curl, wget, vim, tree
- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)

## Source

Build from source or contribute: [opencode-devbox on Gitea](https://gitea.jordbo.se/joakimp/opencode-devbox)