opencode-devbox/DOCKER_HUB.md

opencode-devbox

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

Designed for teams who want a reproducible coding-agent setup that runs the same on every laptop and CI runner — without forcing each developer to install Bun, Node, AWS CLI, mempalace, or maintain shell config drift across machines.

Image Variants

Tag	Description
latest / vX.Y.Z	Base image — opencode, Node.js, AWS CLI, dev tools
latest-omos / vX.Y.Z-omos	Base + oh-my-opencode-slim multi-agent orchestration and Bun
latest-with-pi / vX.Y.Z-with-pi	Base + pi as alternative/complementary harness (shares the mempalace install with opencode)
latest-omos-with-pi / vX.Y.Z-omos-with-pi	OMOS + pi together
latest-pi-only / vX.Y.Z-pi-only	pi without opencode — the lean, pi-focused variant (basis of the separate joakimp/pi-devbox image)

All variants support linux/amd64 and linux/arm64.

Quick Start

For a fully-configured environment with persistent state (opencode config, mempalace memory, neovim plugins, bash history) surviving container recreation, use docker-compose. You don't need to clone the repo — just grab two template files:

mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
curl -O https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml
curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
# Edit .env — set OPENCODE_PROVIDER, the matching API key,
# WORKSPACE_PATH, GIT_USER_NAME, GIT_USER_EMAIL.
docker compose run --rm devbox

This drops you straight into opencode with your project mounted at /workspace. Use bash as the command (e.g. docker compose run --rm devbox bash) to land in a shell first — useful for aws sso login, pi (on *-with-pi variants), or multi-harness workflows.

One-shot run, no persistence:

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

Full setup guide — authentication for each provider (Anthropic, OpenAI, Bedrock SSO + static), persistence model, build args, troubleshooting: https://gitea.jordbo.se/joakimp/opencode-devbox#readme

What's Inside

• opencode — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.).
• pi (in *-with-pi variants) — lightweight TUI coding-agent that coexists with opencode and shares the same mempalace install. Includes the mcp-loader extension so any local-stdio or remote streamable-HTTP MCP server (searxng, gitea, context7, …) can be added by editing ~/.pi/agent/settings.json.
• mempalace — persistent AI memory layer (ChromaDB + SQLite). Wing/diary/knowledge-graph entries are mutually visible to opencode and pi.
• oh-my-opencode-slim (in *-omos variants) — multi-agent orchestration on top of opencode (council, fallback chains, named agents).
• AWS CLI v2 with SSO support, Node.js LTS, Bun (OMOS variants), uv (Python), gosu for clean UID/GID adjustment to match your host workspace.
• MCP wrappers for mempalace pre-installed and pre-wired to both harnesses.

Authentication

The container reads provider credentials from environment variables and host-mounted config:

• Anthropic / OpenAI / Groq / others: set OPENCODE_PROVIDER and the corresponding *_API_KEY via -e or .env.
• AWS Bedrock (SSO): mount ~/.aws from the host, OPENCODE_PROVIDER=amazon-bedrock, then aws sso login inside the container. Tokens persist across container restarts via the host bind-mount.
• OAuth / device-code providers: auth state lives in opencode's config, which is persisted via the devbox-opencode-config named volume.

Full Bedrock walkthrough (IAM roles, permissions, multi-account setups): see the AWS Bedrock Authentication section on gitea.

Persistence

Volume	Mount	Survives
devbox-opencode-config	~/.config/opencode	container recreate, image rebuild
devbox-pi-config	~/.pi	container recreate, image rebuild — incl. user-installed pi packages via pi install (NPM_CONFIG_PREFIX points into the volume)
devbox-palace (uncomment)	~/.mempalace	container recreate, image rebuild — palace data is precious, treat as primary storage
devbox-chroma-cache	~/.cache/chroma	container recreate (model cache, disposable — re-downloads in seconds)

Workspace bind-mount (/workspace) is your project directory on the host, so source code is never inside the container.

Full persistence reference, including multi-user (SIGNUM) isolation and host bind-mount alternatives: see the README on gitea.

Where to Go Next

• Full README with build args, every feature in detail, troubleshooting: https://gitea.jordbo.se/joakimp/opencode-devbox
• CHANGELOG for version history: https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/CHANGELOG.md
• Issues / source / docker-compose templates: https://gitea.jordbo.se/joakimp/opencode-devbox
• Agent-facing internals (for future maintainers / coding agents working in the repo): https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/AGENTS.md

Sibling images

• joakimp/pi-devbox — pi-only image built on top of this image's base layer. Smaller (~700 MB) and version-tracks the pi npm package directly. Use this if you want pi without opencode. Source: https://gitea.jordbo.se/joakimp/pi-devbox

License

MIT. See https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/LICENSE.

---

This description is generated by scripts/generate-dockerhub-md.py from a hand-maintained template. Edit the template (not this file) and regenerate.