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 -u developer devbox opencode

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

# When done
docker rm -f devbox

Note: Always use -u developer with docker exec — the container starts as root for UID adjustment, then drops to developer. Without -u developer, exec runs as root.

Environment Variables

All configuration is done via environment variables, typically stored in a .env file.

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 SSO profile name	default

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

Initial Setup

1. Create a project directory

mkdir -p ~/projects

2. Create a .env file

Create a .env file with your configuration. Examples for each provider:

Anthropic:

OPENCODE_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com

OpenAI:

OPENCODE_PROVIDER=openai
OPENAI_API_KEY=sk-...
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com

AWS Bedrock (SSO):

OPENCODE_PROVIDER=amazon-bedrock
OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
AWS_REGION=eu-west-1
AWS_PROFILE=your-profile-name
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com

3. AWS SSO setup (Bedrock users only)

AWS SSO requires a ~/.aws/config file on the host with your SSO session configuration. If you already have this on another machine, copy it:

scp -r user@other-machine:~/.aws ~/.aws

Or configure from scratch:

aws configure sso

You'll be prompted for:

• SSO session name
• SSO start URL
• SSO region
• Registration scopes (typically sso:account:access)

The ~/.aws directory must be mounted into the container (see docker-compose example below).

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/.aws	Host bind mount	✅ Yes — lives on host	AWS credentials/SSO cache
/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

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 persist across restarts when ~/.aws is mounted (recommended for Bedrock users).

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 directory with a docker-compose.yml and a .env file:

mkdir opencode-devbox && cd opencode-devbox

.env — your settings (never commit this):

OPENCODE_PROVIDER=amazon-bedrock
OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
AWS_REGION=eu-west-1
AWS_PROFILE=your-profile-name
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com

docker-compose.yml:

services:
  devbox:
    image: joakimp/opencode-devbox:latest
    stdin_open: true
    tty: true
    env_file:
      - .env
    environment:
      - TERM=xterm-256color
    volumes:
      - ~/projects:/workspace
      - ~/.ssh:/home/developer/.ssh:ro
      - devbox-data:/home/developer/.local/share/opencode
      # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
      # - ~/.aws:/home/developer/.aws
      # 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

volumes:
  devbox-data:

Docker Compose loads .env automatically from the same directory. All variables from .env are passed to the container via env_file. Do not hardcode provider settings in the environment: section — use .env instead.

Then:

# Start in background
docker compose up -d

# Open a shell (always use -u developer with exec)
docker compose exec -u developer devbox bash

# For Bedrock: authenticate, then start opencode
aws sso login --sso-session <your-session> --use-device-code
opencode

# Or run opencode directly (if no SSO needed)
docker compose exec -u developer devbox opencode

# One-shot mode (creates and removes container)
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)

Optional (build from source)

The pre-built Docker Hub image ships with the core toolset above. When building from source, additional features are available via build args:

• oh-my-opencode-slim (INSTALL_OMOS=true) — multi-agent orchestration plugin with Bun, tmux, and 6 specialized agents (Orchestrator, Explorer, Oracle, Librarian, Designer, Fixer)
• Python 3 (INSTALL_PYTHON=true) — Python 3 + pip + venv
• Go (INSTALL_GO=true) — Go toolchain

Source

Build from source or contribute: opencode-devbox on Gitea