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 |

## Volumes

| Host Path | Container Path | Purpose |
|---|---|---|
| Your project directory | `/workspace` | Code you want to work on |
| `~/.ssh` | `/home/developer/.ssh:ro` | SSH keys for git (read-only) |
| (optional) `~/.aws` | `/home/developer/.aws:ro` | AWS credentials/config |
| (optional) Custom config | `/home/developer/.config/opencode/opencode.json:ro` | Full opencode config with MCP servers, etc. |

### Persisting opencode data

To keep opencode state (session history, memory) between runs, add a named volume:

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

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

volumes:
  devbox-data:
```

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` (UID 1000) with sudo access

## Source

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