# opencode-devbox 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. 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](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration and Bun | | `latest-with-pi` / `vX.Y.Z-with-pi` | Base + [pi](https://github.com/earendil-works/pi) as alternative/complementary harness (shares the mempalace install with opencode) | | `latest-omos-with-pi` / `vX.Y.Z-omos-with-pi` | OMOS + pi together | 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: ```bash 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:** ```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 ``` Full setup guide — authentication for each provider (Anthropic, OpenAI, Bedrock SSO + static), persistence model, build args, troubleshooting: ## What's Inside - **[opencode](https://opencode.ai)** — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.). - **[pi](https://github.com/earendil-works/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](https://github.com/MemPalace/mempalace)** — persistent AI memory layer (ChromaDB + SQLite). Wing/diary/knowledge-graph entries are mutually visible to opencode and pi. - **[oh-my-opencode-slim](https://github.com/alvinunreal/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]( https://gitea.jordbo.se/joakimp/opencode-devbox#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](https://gitea.jordbo.se/joakimp/opencode-devbox#persistence). ## Where to Go Next - **Full README** with build args, every feature in detail, troubleshooting: - **CHANGELOG** for version history: - **Issues / source / docker-compose templates:** - **Agent-facing internals** (for future maintainers / coding agents working in the repo): ## Sibling images - **[`joakimp/pi-devbox`](https://hub.docker.com/r/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](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) directly. Use this if you want pi without opencode. Source: ## License MIT. See . --- > This description is generated by `scripts/generate-dockerhub-md.py` from a hand-maintained template. Edit the template (not this file) and regenerate.