Update docs for named volume config, skillset auto-deploy, opencode.jsonc
- README: rewrite config/skills sections for named volume and auto-deploy, add Context7 MCP docs, update all opencode.json→opencode.jsonc refs, add SKILLSET_CONTAINER_PATH to env var table - CHANGELOG: add v1.14.32b entry documenting breaking changes and features - AGENTS.md: update file roles, add skillset and config volume conventions - DOCKER_HUB.md: regenerated (drop Context7 and Shell defaults sections to stay within 25KB Docker Hub limit) - generate-dockerhub-md.py: add Context7 (drop) and Shell defaults (drop) to SECTION_RULES
This commit is contained in:
Joakim Persson
+19
-61
@@ -69,9 +69,6 @@ Bind-mounted directories must exist on the host before starting the container. D
|
||||
```bash
|
||||
# Required: workspace for your projects
|
||||
mkdir -p ~/projects
|
||||
|
||||
# If mounting opencode config (recommended for persistent settings)
|
||||
mkdir -p ~/.config/opencode
|
||||
```
|
||||
|
||||
### Connecting to the container
|
||||
@@ -145,28 +142,34 @@ docker compose exec -u developer devbox aws --version
|
||||
| `OMOS_TMUX` | Enable tmux pane integration for OMOS | `false` |
|
||||
| `OMOS_SKILLS` | Install OMOS recommended skills on first run | `true` |
|
||||
| `OMOS_RESET` | Force regenerate OMOS config on next start | `false` |
|
||||
| `SKILLSET_CONTAINER_PATH` | Path to skillset repo inside container (for auto-deploy when not at /workspace/skillset) | Auto-detect |
|
||||
|
||||
### Custom opencode config
|
||||
|
||||
For full control over opencode settings (MCP servers, custom models, and — on the OMOS variant — oh-my-opencode-slim agents), mount the entire config directory from the host:
|
||||
Opencode configuration is persisted automatically via the named volume `devbox-opencode-config`. This volume is mounted at `/home/developer/.config/opencode` by default — no host directory setup required. All changes to `opencode.jsonc`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json` survive container recreation.
|
||||
|
||||
When an existing `opencode.jsonc` is found in the volume, the `OPENCODE_PROVIDER` auto-config is skipped.
|
||||
|
||||
**Alternative: host bind-mount** — if you specifically want to share config from the host (e.g. to version-control it or sync across machines), replace the named volume with a bind mount:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ~/.config/opencode:/home/developer/.config/opencode
|
||||
```
|
||||
|
||||
This persists all configuration changes across container restarts, including `opencode.json`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json`. When an existing `opencode.json` is found, the `OPENCODE_PROVIDER` auto-config is skipped.
|
||||
|
||||
> **Portability note:** The mounted config runs inside a Linux container. Any absolute paths inside `opencode.json` (for example, host-specific `plugin` entries like `file:///usr/local/lib/node_modules/...` or `file:///opt/homebrew/...`) will not resolve inside the container. Prefer bare package specifiers (e.g. `"oh-my-opencode-slim"`) that resolve via `node_modules` lookup, which works on both macOS and Linux hosts.
|
||||
> **Portability note:** The mounted config runs inside a Linux container. Any absolute paths inside `opencode.jsonc` (for example, host-specific `plugin` entries like `file:///usr/local/lib/node_modules/...` or `file:///opt/homebrew/...`) will not resolve inside the container. Prefer bare package specifiers (e.g. `"oh-my-opencode-slim"`) that resolve via `node_modules` lookup, which works on both macOS and Linux hosts.
|
||||
|
||||
### Custom skills
|
||||
|
||||
Mount agent skills from the host:
|
||||
Skills are deployed automatically from a skillset repo on container start. The entrypoint detects the skillset location in this order:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ~/.agents/skills:/home/developer/.agents/skills:ro
|
||||
```
|
||||
1. `SKILLSET_CONTAINER_PATH` env var (explicit path to skillset repo inside container)
|
||||
2. `~/skillset` mount (if present)
|
||||
3. `/workspace/skillset` fallback (if your workspace contains a `skillset/` directory)
|
||||
|
||||
When a skillset repo is detected, its skills are symlinked into `~/.agents/skills/` automatically. No manual configuration needed.
|
||||
|
||||
> **Warning:** Do not bind-mount a host `~/.agents/skills` directory directly into the container. This conflicts with the symlink-based auto-deploy mechanism and causes broken skill references.
|
||||
|
||||
### Neovim configuration
|
||||
|
||||
@@ -414,7 +417,7 @@ Without the volume, palace data lives in the container's writable layer and is l
|
||||
|
||||
### MCP integration with opencode
|
||||
|
||||
Add mempalace as an MCP server in your `opencode.json` (inside `~/.config/opencode/`):
|
||||
Add mempalace as an MCP server in your `opencode.jsonc` (inside `~/.config/opencode/`):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -498,7 +501,7 @@ The image includes the [official Gitea MCP server](https://gitea.com/gitea/gitea
|
||||
GITEA_ACCESS_TOKEN=your_token_here
|
||||
```
|
||||
|
||||
3. Enable the gitea MCP server in your `opencode.json`:
|
||||
3. Enable the gitea MCP server in your `opencode.jsonc`:
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
@@ -516,51 +519,6 @@ The image includes the [official Gitea MCP server](https://gitea.com/gitea/gitea
|
||||
|
||||
The server is installed but disabled by default — it requires authentication to be useful.
|
||||
|
||||
## Shell defaults
|
||||
|
||||
The image ships a baked `.bash_aliases` and `.inputrc` with quality-of-life defaults. On first container start they are copied from `/etc/skel-devbox/` into `/home/developer/` **only if the target file does not already exist** — so host bind-mounts and any version you've customized inside the container are never overwritten on upgrade.
|
||||
|
||||
Defaults you get out of the box:
|
||||
|
||||
- **Prefix history search** on Up/Down arrows (type `git `, press Up, walk back through prior `git ...` commands only). Ctrl-Up / Ctrl-Down still step through full history.
|
||||
- **Persistent history** — `$HISTFILE` points at `~/.cache/bash/history`, backed by the `devbox-shell-history` named volume so history survives container recreation. Timestamps, 100 000 entries, dedup.
|
||||
- **Case-insensitive tab completion**, coloured completion lists, `show-all-if-ambiguous`.
|
||||
- **Aliases** — `ls`/`ll`/`la` use `eza`, `cat` uses `bat`, `gs`/`gd`/`gl` for git, safe `rm`/`mv`/`cp`.
|
||||
- **Integrations** — `zoxide` (`z <fragment>` to jump), `fzf` Ctrl-R / Ctrl-T key bindings.
|
||||
- **Prompt marker** — `[devbox]` prefix so it's always obvious you're inside the container.
|
||||
|
||||
### Overriding the defaults
|
||||
|
||||
**Option A — bind-mount host files.** Uncomment the bind-mount lines in `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
- ~/.bash_aliases:/home/developer/.bash_aliases:ro
|
||||
- ~/.inputrc:/home/developer/.inputrc:ro
|
||||
```
|
||||
|
||||
> **Single-file bind-mount caveat (all platforms):** Docker bind-mounts the file's **inode**, not its path. When editors like vim, nvim, VS Code, or `sed -i` save a file, they write to a temp file and `rename()` it over the original — creating a new inode. The container stays pinned to the old (now unlinked) inode and never sees the update. This is a kernel limitation ([Docker #15793](https://github.com/moby/moby/issues/15793)), not fixable by Docker. Append-only writes (`echo "alias foo=bar" >> file`) are safe because they modify the same inode. **Workaround:** mount the parent directory instead of the single file (e.g. `~/.config/devbox-shell:/home/developer/.config/devbox-shell:ro`) and source files from there.
|
||||
|
||||
**Option B — customize inside the container.** Just edit `~/.bash_aliases` or `~/.inputrc` as normal. Pair this with a bind-mount or named volume on the home dir if you want the edits to survive container recreation.
|
||||
|
||||
### Restoring or diffing defaults
|
||||
|
||||
The skel files remain available inside every container at `/etc/skel-devbox/`. Useful commands:
|
||||
|
||||
```bash
|
||||
# See what the image currently ships
|
||||
cat /etc/skel-devbox/.bash_aliases
|
||||
|
||||
# Diff your current config against the upstream defaults
|
||||
diff ~/.bash_aliases /etc/skel-devbox/.bash_aliases
|
||||
|
||||
# Reset to the baked defaults
|
||||
cp /etc/skel-devbox/.bash_aliases ~/.bash_aliases
|
||||
|
||||
# …or delete the file and recreate the container — the entrypoint
|
||||
# copies from /etc/skel-devbox/ on next start if the target is absent
|
||||
rm ~/.bash_aliases
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
@@ -598,9 +556,9 @@ Container (Debian trixie)
|
||||
| `/home/developer/.rustup` | Named volume `devbox-rustup` (if configured) | ✅ Yes | Rust toolchains |
|
||||
| `/home/developer/.cargo` | Named volume `devbox-cargo` (if configured) | ✅ Yes | Cargo binaries, registry cache |
|
||||
| `/home/developer/.vscode-server` | Named volume `devbox-vscode` (if configured) | ✅ Yes | VS Code server and extensions |
|
||||
| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes | opencode.json, skills, plus `oh-my-opencode-slim.json` on the OMOS variant |
|
||||
| `/home/developer/.config/opencode` | Named volume `devbox-opencode-config` | ✅ Yes | `opencode.jsonc`, skills, plus `oh-my-opencode-slim.json` on the OMOS variant |
|
||||
|
||||
**opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, mount the config directory from the host (see Custom opencode config above).
|
||||
**opencode config** (`opencode.jsonc`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, use the named volume (default) or bind-mount from host (see Custom opencode config above).
|
||||
|
||||
## Source
|
||||
|
||||
|
||||
Reference in New Issue
Block a user