joakimp
f86c4b18cf
Validate / docs-check (push) Successful in 16s
Validate / validate-base (push) Successful in 11m16s
Validate / validate-omos (push) Failing after 18m33s
Validate / validate-with-pi (push) Successful in 13m46s
Validate / validate-omos-with-pi (push) Failing after 19m52s
The previous derive-from-README mechanism (split_sections, SECTION_RULES, TRIM_SUBSECTIONS, REPLACEMENTS) generated a 24 997 byte Hub doc with 3 byte headroom against the 25 kB Hub limit. Every README addition forced a 'trim something else first' exercise, and the resulting copy was awkward (terse, repetitive linkbacks injected mid-section). Replace with a single hand-maintained HUB_TEMPLATE constant. The Hub doc is now intentionally slim (~5.5 kB, ~78 percent headroom) and focuses on what Hub readers actually need: elevator pitch, image variants, quick start, what's inside, auth, persistence, and link-outs to the gitea README for depth. Trade-off: when image-variants or quick-start change, update HUB_TEMPLATE here too. That coupling is now explicit and local rather than spread across SECTION_RULES + REPLACEMENTS + TRIM machinery, and most README edits no longer require regenerating DOCKER_HUB.md at all. Generator simplified from 323 lines to 199 lines (270-line net reduction across the script + DOCKER_HUB.md). README and Hub doc are now independent surfaces. CHANGELOG and AGENTS updated to reflect the new coupling. Release-day checklist tightened: README -> regenerate DOCKER_HUB ONLY if HUB_TEMPLATE changed -> promote CHANGELOG -> grep AGENTS -> commit -> tag.
96 lines
5.4 KiB
Markdown
96 lines
5.4 KiB
Markdown
# 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/mariozechner/pi-coding-agent) 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
|
|
|
|
```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
|
|
```
|
|
|
|
Drops you straight into opencode with your project mounted at `/workspace`.
|
|
|
|
For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
|
|
|
|
```bash
|
|
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`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
|
|
|
|
For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
|
|
|
|
## What's Inside
|
|
|
|
- **[opencode](https://opencode.ai)** — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.).
|
|
- **[pi](https://github.com/mariozechner/pi-coding-agent)** *(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: <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>
|
|
|
|
## 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.
|