opencode-devbox/DOCKER_HUB.md

opencode-devbox — Docker Hub

Portable AI developer environment for opencode. Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.

Quick Start

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

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:

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

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:

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

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:

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:

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:

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:

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