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.

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

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:

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