Bump opencode to 1.14.28

Gitea Actions runners accumulate buildkit cache, stale containers,
and unused images. Without periodic cleanup the disk fills and builds
stall during image push (observed: build-omos hung at 'pushing layers'
for 1.5h on a 77%-full disk).

Add a 'CI runner maintenance' section to deploy/README.md with two
cleanup layers: a daily cron job (prunes anything >72h old) and
Docker daemon builder GC (caps buildkit cache at 10 GB).

.env.example

@@ -7,7 +7,7 @@
 OPENCODE_PROVIDER=anthropic
 
 # Model override (optional, defaults per provider)
-# OPENCODE_MODEL=anthropic/claude-sonnet-4-5
+# OPENCODE_MODEL=anthropic/claude-sonnet-4-6
 
 # ── API Keys (set the one matching your provider) ────────────────────
 # ANTHROPIC_API_KEY=
@@ -30,3 +30,15 @@ WORKSPACE_PATH=~/projects
 
 # Path to SSH keys on host
 SSH_KEY_PATH=~/.ssh
+
+# ── Locale (defaults to en_US.UTF-8) ─────────────────────────────────
+# LANG=sv_SE.UTF-8
+# LANGUAGE=sv_SE:sv
+# LC_ALL=sv_SE.UTF-8
+
+# ── oh-my-opencode-slim (multi-agent orchestration) ──────────────────
+# Requires image built with INSTALL_OMOS=true
+# ENABLE_OMOS=false
+# OMOS_TMUX=false              # Enable tmux multiplexer integration
+# OMOS_SKILLS=true             # Install recommended skills (simplify, agent-browser, cartography)
+# OMOS_RESET=false             # Force regenerate oh-my-opencode-slim config on next start

.env.shared.example

@@ -0,0 +1,33 @@
+# ── Shared machine setup ─────────────────────────────────────────────
+# SIGNUM isolates your container name and named volumes from other users.
+#
+# Own-account mode (each user has their own OS login):
+#   Leave SIGNUM commented out — it defaults to your OS username ($USER).
+# SIGNUM=
+#
+# Shared-account mode (everyone logs in as the same OS user):
+#   Uncomment and set to your unique identifier.
+# SIGNUM=your-signum-here
+
+# ── Provider ─────────────────────────────────────────────────────────
+OPENCODE_PROVIDER=amazon-bedrock
+OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
+AWS_REGION=eu-west-1
+AWS_PROFILE=default
+
+# ── Git ──────────────────────────────────────────────────────────────
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=your.name@example.com
+
+# ── Paths (adjust to your layout) ───────────────────────────────────
+# Default: ~/src mounted as /workspace
+# WORKSPACE_PATH=~/src
+
+# SSH keys — defaults to shared ~/.ssh
+# If you have per-user keys: SSH_KEY_PATH=~/<signum>/.ssh
+# SSH_KEY_PATH=~/.ssh
+
+# ── Locale (defaults to en_US.UTF-8) ────────────────────────────────
+# LANG=sv_SE.UTF-8
+# LANGUAGE=sv_SE:sv
+# LC_ALL=sv_SE.UTF-8

.gitea/workflows/docker-publish.yml

@@ -6,7 +6,7 @@ on:
       - 'v*'
 
 jobs:
-  build-and-push:
+  build-base:
     runs-on: ubuntu-latest
     container:
       image: catthehacker/ubuntu:act-latest
@@ -14,11 +14,18 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Force IPv4 for Docker Hub
+        run: |
+          # Prefer IPv4 to avoid intermittent IPv6 connectivity failures
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
 
       - name: Login to Docker Hub
         uses: docker/login-action@v4
@@ -32,7 +39,7 @@ jobs:
           VERSION=${GITHUB_REF#refs/tags/}
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
 
-      - name: Build and push
+      - name: Build and push (base)
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -42,18 +49,83 @@ jobs:
             ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}
             ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest
 
+  build-omos:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: |
+          # Prefer IPv4 to avoid intermittent IPv6 connectivity failures
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Build and push (omos)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            INSTALL_OMOS=true
+          tags: |
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}-omos
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest-omos
+
+  update-description:
+    runs-on: ubuntu-latest
+    needs: [build-base, build-omos]
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
       - name: Update Docker Hub description
         run: |
-          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/users/login/ \
+          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \
             -H "Content-Type: application/json" \
-            -d '{"username":"${{ vars.DOCKERHUB_USERNAME }}","password":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
-            | jq -r .token)
-          jq -n \
-            --arg full "$(cat DOCKER_HUB.md)" \
+            -d '{"identifier":"${{ vars.DOCKERHUB_USERNAME }}","secret":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
+            | jq -r .access_token)
+          if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
+            echo "::error::Failed to authenticate with Docker Hub API"
+            exit 1
+          fi
+          HTTP_CODE=$(jq -n \
+            --rawfile full DOCKER_HUB.md \
             --arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support." \
             '{"full_description": $full, "description": $short}' | \
-            curl -s -o /dev/null -w "%{http_code}" -X PATCH \
+            curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \
               "https://hub.docker.com/v2/repositories/${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox/" \
-              -H "Authorization: JWT $TOKEN" \
+              -H "Authorization: Bearer $TOKEN" \
               -H "Content-Type: application/json" \
-              -d @-
+              -d @-)
+          echo "Docker Hub API returned: $HTTP_CODE"
+          if [ "$HTTP_CODE" != "200" ]; then
+            echo "Response body:"
+            cat /tmp/hub-response.txt
+            echo "::error::Docker Hub description update failed with HTTP $HTTP_CODE"
+            exit 1
+          fi

.gitignore

@@ -3,3 +3,6 @@
 *.swo
 *~
 .DS_Store
+
+# Personal cloud-init overrides (not shared)
+deploy/my-cloud-init.yml

AGENTS.md

@@ -0,0 +1,56 @@
+# AGENTS.md
+
+## Project overview
+
+Docker image packaging [opencode](https://opencode.ai) into a production-ready dev container. Two image variants (base and omos) are published to Docker Hub via Gitea Actions CI. Not a library or application — this is infrastructure (Dockerfile, entrypoint scripts, docker-compose, documentation).
+
+## File roles
+
+- `Dockerfile` — single multi-stage build for both variants. OMOS variant is controlled by `INSTALL_OMOS=true` build arg. All GitHub-sourced binaries are pinned with version ARGs.
+- `entrypoint.sh` — runs as root: UID/GID adjustment, SSH permissions, volume ownership fixes. Then drops to developer via gosu.
+- `entrypoint-user.sh` — runs as developer: git config, opencode.json generation from env vars, OMOS setup.
+- `DOCKER_HUB.md` — pushed to Docker Hub description via CI API call. Must stay under 25KB. Short description field must be ≤100 bytes.
+- `README.md` — source repo documentation. Must stay in sync with DOCKER_HUB.md (both describe the same features but for different audiences).
+- `.gitea/workflows/docker-publish.yml` — CI pipeline: three parallel jobs (build-base, build-omos, update-description). Triggered by tag push only.
+
+## Versioning scheme
+
+Tags follow `v{opencode_version}[letter]` — e.g. `v1.14.20` for the first build on a new opencode release, and `v1.14.20b`, `v1.14.20c`, … for subsequent rebuilds on the same opencode version.
+
+- The number tracks the opencode npm version (see `OPENCODE_VERSION` ARG in `Dockerfile`).
+- **No letter suffix** on the first build of a new opencode version — the bare `v{opencode_version}` tag is the canonical release.
+- **Letter suffix is the build ordinal**, starting at `b` for the second build. The letter `a` is **never used** — think of the suffix as counting rebuilds: `b = 2nd, c = 3rd, d = 4th, …`. For opencode version `1.14.20`: first build `v1.14.20`, second `v1.14.20b`, third `v1.14.20c`, and so on.
+- A letter suffix is only used for container-level rebuilds — tooling changes, CVE fixes, doc-driven rebuilds, entrypoint bugfixes — that don't change the underlying opencode version.
+
+CI produces four Docker Hub tags per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`.
+
+When bumping the opencode version, also bump `OPENCODE_VERSION` in `Dockerfile` and update the comment in `.env.example` if it names a specific model/version for context.
+
+## Critical conventions
+
+- **entrypoint.sh volume ownership loop** — when adding a new named volume mount point, add it to the `for dir in ...` loop in `entrypoint.sh` so root-owned volumes get chowned on startup.
+- **Three docs to keep in sync** — Dockerfile changes that add tools or features must be reflected in `README.md`, `DOCKER_HUB.md`, and `.env.example`. The docker-compose examples in both docs must match the source `docker-compose.yml` pattern.
+- **GitHub-sourced binaries** — fzf, gosu, git-lfs, neovim, bat, eza, zoxide, uv, rustup are installed from upstream releases (not apt) with pinned versions. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64).
+- **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.
+- **Docker Hub description update** — uses `/v2/auth/token` endpoint (not the deprecated `/v2/users/login`). Auth uses `identifier`/`secret` fields, returns `access_token`, sent as `Bearer`. Short description must be ≤100 bytes.
+
+## CI quirks
+
+- Both build jobs include an IPv4 preference step (`gai.conf` + `driver-opts: network=host` for buildx) to work around intermittent IPv6 failures on the Gitea runners.
+- `update-description` job runs only when both builds succeed (`needs: [build-base, build-omos]`).
+- Tags must be pushed to trigger CI. Pushing to `main` alone does not build images.
+
+## Testing changes
+
+No test suite. Verify by:
+1. Building locally: `docker compose build`
+2. Running: `docker compose run --rm devbox bash`
+3. Checking tool availability inside container: `nvim --version`, `bat --version`, `uv --version`, etc.
+4. For entrypoint changes: test with a non-1000 UID workspace to verify UID adjustment and volume ownership fixes.
+
+## Commit style
+
+Imperative mood, first line summarizes the change. Multi-line body explains "why" when non-obvious. Examples from history:
+- `Fix ownership of named volume mount points in entrypoint`
+- `Add uv package manager to base image for on-demand Python support`
+- `Upgrade base image from Debian bookworm to trixie (current stable)`

CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to the opencode-devbox container image.
+
+Tags follow `v{opencode_version}[letter]` — bare tag for the first build on a new opencode release, letter suffix (`b`, `c`, …) for container-level rebuilds on the same version. See [AGENTS.md](AGENTS.md#versioning-scheme) for details.
+
+---
+
+## v1.14.28 — 2026-04-26
+
+Bump opencode to 1.14.28.
+
+## v1.14.25 — 2026-04-25
+
+Bump opencode to 1.14.25. Also includes container-level changes since v1.14.22b:
+- Add `python3-pip` and `python3-venv` to base image (fixes Mason LSP installs).
+- Add `devbox-nvim-data` named volume for neovim plugin/Mason persistence.
+- Add `devbox-zoxide` named volume for zoxide directory history persistence.
+- Bake devbox-shell bridge line into `/etc/skel-devbox/.bash_aliases`.
+- Add CHANGELOG.md with full release history.
+
+## v1.14.22b — 2026-04-23
+
+**Fix Mason LSP installs, persist nvim data, devbox-shell bridge.**
+
+- **Fix:** Add `python3-pip` and `python3-venv` to base image. Mason creates a Python venv per LSP package and pip-installs into it; Debian trixie ships python3 without ensurepip, so venv creation failed and every Mason Python package (ruff, ansible-lint) errored on every nvim start.
+- **Feature:** Add `devbox-nvim-data` named volume at `~/.local/share/nvim` — Lazy plugin cache and Mason LSP installs now persist across `--force-recreate`.
+- **Feature:** Add `devbox-zoxide` named volume at `~/.local/share/zoxide` — zoxide directory history persists across recreates.
+- **Feature:** Bake the devbox-shell bridge line into `/etc/skel-devbox/.bash_aliases` — hosts using the `~/.config/devbox-shell/` directory-mount pattern get automatic sourcing without manual setup after recreate.
+
+## v1.14.22 — 2026-04-23
+
+Bump opencode to 1.14.22.
+
+## v1.14.21 — 2026-04-23
+
+**Opencode 1.14.21 + zoxide persistence + multi-user fixes.**
+
+- Bump opencode to 1.14.21.
+- Fix single-file bind-mount caveat: document the kernel-level inode issue (affects all platforms, not just Docker Desktop).
+- Pin project name in default `docker-compose.yml` — directory renames no longer orphan named volumes.
+- Fix volume collision in shared-machine compose: scope project name by `SIGNUM`.
+- Auto-detect OS username (`$USER`) for volume isolation in own-account mode.
+- Document the upgrade ritual for reconciling VM compose files.
+- Add multi-user setup pointer in DOCKER_HUB.md.
+
+## v1.14.20b — 2026-04-21
+
+**Fix `[devbox]` prompt marker lost on `exec bash`.**
+
+- The PS1 prefix guard used an exported env var that survived `exec bash`, but PS1 itself doesn't — so the new shell skipped adding the prefix. Replaced with a substring check on PS1 itself.
+- Clarify tag-letter convention in AGENTS.md: suffix is the build ordinal, `a` is never used.
+
+## v1.14.20 — 2026-04-21
+
+**Opencode 1.14.20 + PROMPT_COMMAND/zoxide fix.**
+
+- Bump opencode to 1.14.20.
+- Fix `PROMPT_COMMAND` collision with zoxide: `history -a;` followed by zoxide's `;__zoxide_hook` produced `;;` which bash rejected on every prompt. Moved history-flush after zoxide init, using newline separator.
+- Includes all v1.14.19c shell-defaults work (baked `.bash_aliases`/`.inputrc` via `/etc/skel-devbox/`, skel-copy on first run, `devbox-shell-history` named volume).
+
+## v1.14.19d — 2026-04-21
+
+*Superseded by v1.14.20 before building. Tagged but never built.*
+
+## v1.14.19c — 2026-04-21
+
+**Bash history persistence, shell defaults, GID auto-detect.**
+
+- **Feature:** Bash history persists across `--force-recreate` via `devbox-shell-history` named volume at `~/.cache/bash`.
+- **Feature:** Quality-of-life shell defaults shipped in `/etc/skel-devbox/` and copied to `~/` only if absent: prefix history search on Up/Down, 100k-entry timestamped dedup history, coloured case-insensitive tab completion, eza/bat aliases, zoxide/fzf integrations, `[devbox]` prompt marker.
+- **Feature:** Skel-copy pattern — host bind-mounts and in-container customizations are never overwritten on upgrade.
+- **Fix:** Entrypoint now detects workspace UID and GID independently. Hosts with UID 1000 but non-1000 GID (e.g. Debian's `useradd` default GID 1001) get correct group remapping.
+- **Docs:** SSH banner-timeout troubleshooting (CGNAT), shell defaults section, skel restore/diff commands.
+
+## v1.14.19b — 2026-04-20
+
+**Ownership fixes and config/docs refresh.**
+
+- **Fix:** Root-owned parent dirs left behind by nested named-volume mounts. Entrypoint now chowns `.local`, `.local/share`, `.local/state`, `.config` before leaf mount points.
+- **Fix:** `deploy/sync-to-vm.sh` no longer preserves host GIDs (`rsync -a` → `-rlptDz`).
+- Default model IDs refreshed (claude-sonnet-4-6, gpt-5.4, global Bedrock inference profile).
+- Documentation gates oh-my-opencode-slim references to the OMOS variant.
+
+## v1.14.19 — 2026-04-20
+
+Bump opencode to 1.14.19.
+
+## v1.14.18 — 2026-04-19
+
+Fix Bun download URL: remove non-existent LATEST file fetch.
+
+## v1.4.17 — 2026-04-19
+
+Bump opencode to v1.4.17, add `file` utility to base image.
+
+## v1.4.12 — 2026-04-18
+
+Bump opencode to v1.4.12.
+
+## v1.4.11 — 2026-04-18
+
+Bump opencode to v1.4.11.
+
+## v1.4.7 — 2026-04-17
+
+Bump opencode to v1.4.7.
+
+## v1.4.6 — 2026-04-15
+
+Bump opencode to v1.4.6.
+
+## v1.4.3k — 2026-04-13
+
+Fix Bedrock config: add `AWS_PROFILE` to generated config, add `.agents/skills` to volume ownership fix.
+
+## v1.4.3j — 2026-04-13
+
+Upgrade base image from Debian bookworm to trixie (current stable). Bookworm EOL June 2026; trixie supported until 2028/LTS 2030.
+
+## v1.4.3i — 2026-04-12
+
+Add rustup for on-demand Rust support, document JS/TS development.
+
+## v1.4.3h — 2026-04-12
+
+Add uv package manager to base image for on-demand Python support.
+
+## v1.4.3g — 2026-04-12
+
+Fix IPv6 connectivity failures: force IPv4 preference in CI builds.
+
+## v1.4.3f — 2026-04-11
+
+Add error handling to Docker Hub description update step.
+
+## v1.4.3e — 2026-04-10
+
+Fix CVEs: install git-lfs from GitHub (Go 1.25), document Go versions for gosu/fzf.
+
+## v1.4.3d — 2026-04-10
+
+Fix CVEs: install gosu 1.19 and fzf 0.71.0 from GitHub releases instead of Debian packages.
+
+## v1.4.3c — 2026-04-10
+
+Fix CVEs: install gosu from GitHub release instead of Debian package (Go 1.19.8 → current).
+
+## v1.4.3b — 2026-04-10
+
+Fix entrypoint crash on read-only SSH mount.
+
+## v1.4.3 — 2026-04-10
+
+Bump opencode to 1.4.3.
+
+## v1.4.2 — 2026-04-10
+
+Initial release. Fix CI: use vars for username, secrets for token.

DOCKER_HUB.md

@@ -2,6 +2,17 @@
 
 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.
 
+## Image Variants
+
+Two image variants are published for each release:
+
+| 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 |
+
+Both variants support `linux/amd64` and `linux/arm64`.
+
 ## Quick Start
 
 ```bash
@@ -46,25 +57,21 @@ docker run -d --name devbox \
   joakimp/opencode-devbox:latest sleep infinity
 
 # Shell 1: run opencode
-docker exec -it devbox opencode
+docker exec -it -u developer devbox opencode
 
 # Shell 2 (separate terminal): aws, git, etc.
-docker exec -it devbox bash
+docker exec -it -u developer devbox bash
 
 # When done
 docker rm -f devbox
 ```
 
-With docker-compose this is simpler:
-
-```bash
-docker compose up -d
-docker compose exec devbox opencode     # terminal 1
-docker compose exec devbox bash         # terminal 2
-```
+> **Note:** Always use `-u developer` with `docker exec` — the container starts as root for UID adjustment, then drops to `developer`. Without `-u developer`, exec runs as root.
 
 ## Environment Variables
 
+All configuration is done via environment variables, typically stored in a `.env` file.
+
 ### Provider Configuration
 
 | Variable | Description | Default |
@@ -87,14 +94,7 @@ Set the key matching your provider:
 | Variable | Description | Default |
 |---|---|---|
 | `AWS_REGION` | AWS region | `us-east-1` |
-| `AWS_PROFILE` | AWS profile name | `default` |
-
-For SSO authentication, start with `bash` and run:
-
-```bash
-aws sso login --sso-session <your-session> --use-device-code
-opencode
-```
+| `AWS_PROFILE` | AWS SSO profile name | `default` |
 
 ### Git
 
@@ -114,14 +114,108 @@ The entrypoint automatically detects the owner of `/workspace` and adjusts the c
 | `USER_UID` | Container user UID | Auto-detect from `/workspace` owner |
 | `USER_GID` | Container user GID | Auto-detect from `/workspace` owner |
 
+### Locale and Editor
+
+The container defaults to English (`en_US.UTF-8`) and neovim as the editor. Override via environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `LANG` | System locale | `en_US.UTF-8` |
+| `LANGUAGE` | Language priority list | `en_US:en` |
+| `LC_ALL` | Override all locale settings | `en_US.UTF-8` |
+| `EDITOR` | Default text editor | `nvim` |
+
+Pre-generated locales: `en_US`, `en_GB`, `sv_SE`, `da_DK`, `nb_NO`, `fi_FI`, `de_DE`, `fr_FR`, `es_ES`, `it_IT`, `pt_BR`, `nl_NL`, `pl_PL`, `ja_JP`, `ko_KR`, `zh_CN` (all UTF-8).
+
+Example for Swedish:
+
 ```bash
-docker run -it --rm \
-  -e USER_UID=$(id -u) \
-  -e USER_GID=$(id -g) \
-  -v ~/projects:/workspace \
-  joakimp/opencode-devbox:latest
+LANG=sv_SE.UTF-8
+LANGUAGE=sv_SE:sv
+LC_ALL=sv_SE.UTF-8
 ```
 
+To add a locale not in the list, run inside the container:
+
+```bash
+sudo sed -i '/xx_XX.UTF-8/s/^# //g' /etc/locale.gen
+sudo locale-gen
+```
+
+Replace `xx_XX` with the desired locale (e.g. `ru_RU`, `tr_TR`). This change does not persist across container restarts — for permanent additions, build from source and modify the Dockerfile.
+
+## Initial Setup
+
+### 1. Create host directories
+
+Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
+
+```bash
+# Required
+mkdir -p ~/projects
+
+# If mounting opencode config (recommended for persistent settings)
+mkdir -p ~/.config/opencode
+
+# If using AWS Bedrock
+# mkdir -p ~/.aws
+
+# If mounting neovim config
+# mkdir -p ~/.config/nvim
+```
+
+### 2. Create a `.env` file
+
+Create a `.env` file with your configuration. Examples for each provider:
+
+**Anthropic:**
+```bash
+OPENCODE_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+```
+
+**OpenAI:**
+```bash
+OPENCODE_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+```
+
+**AWS Bedrock (SSO):**
+```bash
+OPENCODE_PROVIDER=amazon-bedrock
+OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
+AWS_REGION=eu-west-1
+AWS_PROFILE=your-profile-name
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+```
+
+### 3. AWS SSO setup (Bedrock users only)
+
+AWS SSO requires a `~/.aws/config` file on the host with your SSO session configuration. If you already have this on another machine, copy it:
+
+```bash
+scp -r user@other-machine:~/.aws ~/.aws
+```
+
+Or configure from scratch:
+
+```bash
+aws configure sso
+```
+
+You'll be prompted for:
+- SSO session name
+- SSO start URL
+- SSO region
+- Registration scopes (typically `sso:account:access`)
+
+The `~/.aws` directory must be mounted into the container (see docker-compose example below).
+
 ## Data Storage and Persistence
 
 Understanding what survives container restarts and what doesn't:
@@ -130,53 +224,178 @@ Understanding what survives container restarts and what doesn't:
 |---|---|---|---|
 | `/workspace` | Host bind mount | ✅ Yes — lives on host | Your project files |
 | `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
+| `/home/developer/.aws` | Host bind mount | ✅ Yes — lives on host | AWS credentials/SSO cache |
 | `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
-| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No — regenerated each start | Provider config, MCP server definitions |
-| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes — lives on host | AWS credentials/SSO cache |
+| `/home/developer/.local/state/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | TUI settings (theme, toggles) |
+| `/home/developer/.cache/bash` | Named volume `devbox-shell-history` | ✅ Yes — Docker volume | Bash history (`$HISTFILE`) — survives container recreate |
+| `/home/developer/.local/share/zoxide` | Named volume `devbox-zoxide` | ✅ Yes — Docker volume | Zoxide directory history (`z <fragment>` jump targets) |
+| `/home/developer/.local/share/nvim` | Named volume `devbox-nvim-data` | ✅ Yes — Docker volume | Neovim plugins, Mason LSP installs, Lazy plugin cache |
+| `/home/developer/.local/share/uv` | Named volume (if configured) | ✅ Yes — Docker volume | Python installs, uv tool installs |
+| `/home/developer/.rustup` | Named volume (if configured) | ✅ Yes — Docker volume | Rust toolchains |
+| `/home/developer/.cargo` | Named volume (if configured) | ✅ Yes — Docker volume | Cargo binaries, registry cache |
+| `/home/developer/.vscode-server` | Named volume (if configured) | ✅ Yes — Docker volume | VS Code server and extensions |
+| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, skills, plus `oh-my-opencode-slim.json` on the OMOS variant |
 
 ### Key points
 
 - **Project files** (`/workspace`) are always safe — they're your host filesystem.
-- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start. It only sets provider and model — no MCP servers. To persist MCP server config, mount your own config file (see Custom opencode Config below).
-- **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
-- **AWS SSO tokens** are stored inside the container and lost on restart. Re-run `aws sso login` after restarting.
-
-### Persisting opencode data
-
-Add a named volume to keep session history and memory between runs:
-
-```bash
-docker run -it --rm \
-  -v opencode-data:/home/developer/.local/share/opencode \
-  ... \
-  joakimp/opencode-devbox:latest
-```
+- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start if no existing config is found. To persist config changes, mount the config directory from the host (see Custom opencode Config below).
+- **opencode data** (session history, memory) is lost on container recreation unless you add a named volume.
+- **TUI settings** (theme, toggles) are lost on container recreation unless you add the `devbox-state` named volume.
+- **Bash history** persists via the `devbox-shell-history` volume mounted at `~/.cache/bash`. `HISTFILE` is pre-configured; no setup required.
+- **Python installs** via `uv python install` are lost on container recreation unless you add the `devbox-uv` named volume.
+- **Rust toolchains** via `rustup-init` are lost on container recreation unless you add the `devbox-rustup` and `devbox-cargo` named volumes.
+- **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
 
 ## Custom opencode Config
 
-For full control (MCP servers, custom models, keybindings), mount your own 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:
 
 ```bash
 docker run -it --rm \
-  -v ./my-opencode.json:/home/developer/.config/opencode/opencode.json:ro \
+  -v ~/.config/opencode:/home/developer/.config/opencode \
   ... \
   joakimp/opencode-devbox:latest
 ```
 
-When a config file is mounted, the `OPENCODE_PROVIDER` auto-config is skipped.
+This persists all configuration changes across container restarts. 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.
+
+## Neovim Configuration
+
+The image includes neovim 0.12 with `EDITOR=nvim` set by default. To use your own neovim config (and have plugins auto-install via lazy.nvim on first start), mount it from the host:
+
+```bash
+docker run -it --rm \
+  -v ~/.config/nvim:/home/developer/.config/nvim:ro \
+  ... \
+  joakimp/opencode-devbox:latest
+```
+
+## Python Development with uv
+
+The image includes Python 3.13 (from Debian Trixie) and [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv:
+
+```bash
+# Python 3.13 is available out of the box
+python3 --version
+
+# Use uv for package management
+uv venv
+uv pip install -r requirements.txt
+
+# Or use uv's project workflow (reads pyproject.toml)
+uv sync
+
+# Run a Python script
+uv run python script.py
+
+# Install standalone Python tools
+uvx ruff check .
+
+# Install a newer Python version (persists with devbox-uv volume)
+uv python install 3.14
+```
+
+To persist Python installs across container restarts, add a named volume:
+
+```bash
+docker run -it --rm \
+  -v devbox-uv:/home/developer/.local/share/uv \
+  ... \
+  joakimp/opencode-devbox:latest
+```
+
+Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
+
+## Rust Development with rustup
+
+The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
+
+```bash
+# One-time setup: install Rust toolchain (~300MB, persists with volumes)
+rustup-init -y
+source ~/.cargo/env
+
+# Now use Rust normally
+cargo new my-project
+cargo build
+cargo run
+```
+
+To persist Rust toolchains and cargo data across container restarts, add named volumes:
+
+```bash
+docker run -it --rm \
+  -v devbox-rustup:/home/developer/.rustup \
+  -v devbox-cargo:/home/developer/.cargo \
+  ... \
+  joakimp/opencode-devbox:latest
+```
+
+## JavaScript and TypeScript
+
+The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
+
+```bash
+# Initialize a new project
+npm init -y
+
+# Install dependencies
+npm install
+
+# Run TypeScript (via tsx, ts-node, etc.)
+npx tsx src/index.ts
+```
+
+The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
+
+```bash
+bun init
+bun install
+bun run src/index.ts
+```
+
+Node modules are stored in your project directory under `/workspace` and persist automatically.
+
+## VS Code Integration
+
+VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
+
+**Requirements:** Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. For remote Docker hosts, also install [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
+
+**Steps:**
+
+1. Start the container: `docker compose up -d`
+2. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
+
+For remote Docker hosts (e.g. connecting to a server via SSH), first connect to the remote host with Remote-SSH, then attach to the container from there.
+
+VS Code extensions installed inside the container persist as long as the container exists. For persistent extension storage across container recreations, add a named volume:
+
+```bash
+docker run -it --rm \
+  -v devbox-vscode:/home/developer/.vscode-server \
+  ... \
+  joakimp/opencode-devbox:latest
+```
 
 ## Using docker-compose
 
-Create a `docker-compose.yml` and a `.env` file in the same directory:
+Create a directory with a `docker-compose.yml` and a `.env` file:
 
 ```bash
 mkdir opencode-devbox && cd opencode-devbox
 ```
 
-`.env` — your secrets and settings (never commit this):
+`.env` — your settings (never commit this):
 
 ```bash
-ANTHROPIC_API_KEY=sk-ant-...
+OPENCODE_PROVIDER=amazon-bedrock
+OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
+AWS_REGION=eu-west-1
+AWS_PROFILE=your-profile-name
 GIT_USER_NAME=Your Name
 GIT_USER_EMAIL=you@example.com
 ```
@@ -187,46 +406,155 @@ GIT_USER_EMAIL=you@example.com
 services:
   devbox:
     image: joakimp/opencode-devbox:latest
+    # For multi-agent orchestration, use the omos variant instead:
+    # image: joakimp/opencode-devbox:latest-omos
+    container_name: opencode-devbox
     stdin_open: true
     tty: true
+    env_file:
+      - .env
     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
-      # Optional: mount your own opencode config (MCP servers, custom models, etc.)
-      # - ./opencode.json:/home/developer/.config/opencode/opencode.json:ro
-      # Optional: mount opencode skills from host
-      # - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
+      - devbox-state:/home/developer/.local/state/opencode
+      - devbox-uv:/home/developer/.local/share/uv
+      # Optional: persist Rust toolchains and cargo data
+      # - devbox-rustup:/home/developer/.rustup
+      # - devbox-cargo:/home/developer/.cargo
+      # Optional: persist VS Code server and extensions
+      # - devbox-vscode:/home/developer/.vscode-server
+      # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
+      # - ~/.aws:/home/developer/.aws
+      # Optional: mount opencode config directory (persists config changes across restarts)
+      # - ~/.config/opencode:/home/developer/.config/opencode
+      # Optional: mount opencode agent skills from host
       # - ~/.agents/skills:/home/developer/.agents/skills:ro
+      # Optional: mount neovim config from host (plugins auto-install on first start)
+      # - ~/.config/nvim:/home/developer/.config/nvim:ro
 
 volumes:
   devbox-data:
+  devbox-state:
+  devbox-uv:
+  # devbox-rustup:
+  # devbox-cargo:
+  # devbox-vscode:
 ```
 
-Docker Compose automatically loads `.env` from the same directory as the compose file. The `${VAR}` references are substituted with values from `.env`.
+Docker Compose loads `.env` automatically from the same directory. All variables from `.env` are passed to the container via `env_file`. Do **not** hardcode provider settings in the `environment:` section — use `.env` instead.
 
 Then:
 
 ```bash
+# Start in background
+docker compose up -d
+
+# Open a shell (always use -u developer with exec)
+docker compose exec -u developer devbox bash
+
+# For Bedrock: authenticate, then start opencode
+aws sso login --sso-session <your-session> --use-device-code
+opencode
+
+# Or run opencode directly (if no SSO needed)
+docker compose exec -u developer devbox opencode
+
+# One-shot mode (creates and removes container)
 docker compose run --rm devbox        # direct to opencode
 docker compose run --rm devbox bash   # interactive shell
 ```
 
+## Shell defaults
+
+The image ships baked `.bash_aliases` and `.inputrc` in `/etc/skel-devbox/`. On first container start the entrypoint copies them to `/home/developer/` **only if the target file does not already exist**, so your host bind-mounts or any in-container customization are preserved across upgrades.
+
+- **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** via `$HISTFILE=~/.cache/bash/history`, backed by the `devbox-shell-history` named volume. Survives container recreate. 100 000 entries, time-stamped, dedup.
+- **Case-insensitive tab completion** and coloured completion lists.
+- **Aliases** — `ls`/`ll`/`la` → `eza`, `cat` → `bat`, `gs`/`gd`/`gl` for git, interactive `rm`/`mv`/`cp`.
+- **Integrations** — `zoxide` (`z <fragment>`), `fzf` key bindings (`Ctrl-R`, `Ctrl-T`).
+- **`[devbox]` prompt prefix** so you always know you're in the container.
+
+To override with your host's own files, uncomment the matching bind-mount lines in `docker-compose.yml`. To restore the baked defaults any time: `cp /etc/skel-devbox/.bash_aliases ~/` (or delete the file and recreate the container).
+
 ## What's Included
 
-- **Debian bookworm-slim** — glibc, full terminal/PTY support
+### Base image (`latest`)
+
+- **Debian trixie-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
+- **Dev tools** — git, git-lfs, git-crypt, age, ssh, ripgrep, fd, fzf, bat, eza, zoxide, uv, rustup, jq, make, gcc, g++, curl, wget, neovim 0.12, tmux, htop, tree, rsync
 - **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
 
+### OMOS image (`latest-omos`)
+
+Everything in the base image, plus:
+
+- **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** — multi-agent orchestration plugin
+- **Bun** — JavaScript runtime required by oh-my-opencode-slim
+- **6 specialized agents** — Orchestrator, Explorer, Oracle, Librarian, Designer, Fixer
+
+### Additional runtimes (build from source)
+
+When [building from source](https://gitea.jordbo.se/joakimp/opencode-devbox), additional runtimes are available via build args:
+
+- **Python 3** (`INSTALL_PYTHON=true`) — Python 3 + pip + venv
+- **Go** (`INSTALL_GO=true`) — Go toolchain
+
+## oh-my-opencode-slim (OMOS variant)
+
+The `-omos` image variant includes [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim), which adds a multi-agent layer on top of opencode. An Orchestrator delegates tasks to specialized agents, each configurable with different models and providers.
+
+### Quick start with OMOS
+
+```bash
+docker run -it --rm \
+  -e OPENAI_API_KEY=your-key \
+  -e OPENCODE_PROVIDER=openai \
+  -e ENABLE_OMOS=true \
+  -v ~/projects:/workspace \
+  -v ~/.ssh:/home/developer/.ssh:ro \
+  joakimp/opencode-devbox:latest-omos
+```
+
+On first start, the entrypoint configures oh-my-opencode-slim automatically. The default preset uses OpenAI models.
+
+### OMOS environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `ENABLE_OMOS` | `false` | Activate oh-my-opencode-slim on container start |
+| `OMOS_TMUX` | `false` | Enable tmux pane integration (watch agents in split panes) |
+| `OMOS_SKILLS` | `true` | Install recommended skills (simplify, agent-browser, cartography) |
+| `OMOS_RESET` | `false` | Force regenerate config on next start (backs up existing config) |
+
+### Custom OMOS configuration
+
+If you mount the opencode config directory (see Custom opencode Config above), the `oh-my-opencode-slim.json` file is included and persists across restarts. Edit it directly to control which models power each agent, fallback chains, council setup, and more.
+
+See the [oh-my-opencode-slim configuration docs](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/docs/configuration.md) for the full reference.
+
+### Verifying agents
+
+After starting opencode with OMOS enabled, run inside the opencode session:
+
+```
+ping all agents
+```
+
+All six agents should respond if your provider authentication is working.
+
+## Multi-User Setup
+
+This guide covers single-user setup. For running multiple opencode-devbox instances in parallel — whether each user has their own OS account or everyone shares one login — see the [Multi-user setup section](https://gitea.jordbo.se/joakimp/opencode-devbox#multi-user-setup) in the source repository. It covers volume isolation, the `docker-compose.shared.yml` layout, and the `SIGNUM` / `$USER` auto-detection mechanism.
+
 ## Source
 
 Build from source or contribute: [opencode-devbox on Gitea](https://gitea.jordbo.se/joakimp/opencode-devbox)
+
+See the [Changelog](https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/CHANGELOG.md) for a full release history.

Dockerfile

@@ -1,11 +1,11 @@
 # opencode-devbox — portable AI dev environment
 # Debian-based container with opencode and configurable dev tools
 
-ARG DEBIAN_VERSION=bookworm-slim
+ARG DEBIAN_VERSION=trixie-slim
 FROM debian:${DEBIAN_VERSION} AS base
 
 ARG TARGETARCH
-ARG OPENCODE_VERSION=1.4.3
+ARG OPENCODE_VERSION=1.14.28
 
 LABEL maintainer="joakimp"
 LABEL description="Portable opencode developer container"
@@ -20,29 +20,109 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
     wget \
     git \
-    git-lfs \
     openssh-client \
     gnupg \
     jq \
     ripgrep \
     fd-find \
-    fzf \
     tree \
     less \
-    vim-tiny \
+    htop \
+    tmux \
+    make \
+    patch \
+    diffutils \
+    git-crypt \
+    age \
+    file \
     sudo \
-    gosu \
     locales \
     procps \
     unzip \
+    gcc \
+    g++ \
+    rsync \
+    python3-pip \
+    python3-venv \
     && ln -s /usr/bin/fdfind /usr/local/bin/fd \
     && rm -rf /var/lib/apt/lists/*
 
-# Set locale
-RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
+# ── Go-compiled tools (install from GitHub to avoid CVEs in Debian's old Go builds)
+
+# gosu — privilege de-escalation (built with Go 1.24.6)
+ARG GOSU_VERSION=1.19
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    curl -fsSL "https://github.com/tianon/gosu/releases/download/${GOSU_VERSION}/gosu-${ARCH}" -o /usr/local/bin/gosu && \
+    chmod +x /usr/local/bin/gosu && \
+    gosu --version
+
+# fzf — fuzzy finder (built with Go 1.23.12)
+ARG FZF_VERSION=0.71.0
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    curl -fsSL "https://github.com/junegunn/fzf/releases/download/v${FZF_VERSION}/fzf-${FZF_VERSION}-linux_${ARCH}.tar.gz" | tar -xz -C /usr/local/bin fzf && \
+    fzf --version
+
+# git-lfs — Git Large File Storage (built with Go 1.25)
+ARG GIT_LFS_VERSION=3.7.1
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    curl -fsSL "https://github.com/git-lfs/git-lfs/releases/download/v${GIT_LFS_VERSION}/git-lfs-linux-${ARCH}-v${GIT_LFS_VERSION}.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/git-lfs-${GIT_LFS_VERSION}/git-lfs /usr/local/bin/git-lfs && \
+    rm -rf /tmp/git-lfs-${GIT_LFS_VERSION} && \
+    git lfs install --system && \
+    git-lfs --version
+
+# neovim — modern text editor (pre-built release from GitHub)
+ARG NVIM_VERSION=0.12.1
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://github.com/neovim/neovim/releases/download/v${NVIM_VERSION}/nvim-linux-${ARCH}.tar.gz" | tar -xz -C /opt && \
+    ln -s /opt/nvim-linux-${ARCH}/bin/nvim /usr/local/bin/nvim && \
+    nvim --version | head -1
+
+# bat — syntax-highlighted cat replacement
+ARG BAT_VERSION=0.26.1
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://github.com/sharkdp/bat/releases/download/v${BAT_VERSION}/bat-v${BAT_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/bat-v${BAT_VERSION}-${ARCH}-unknown-linux-musl/bat /usr/local/bin/bat && \
+    rm -rf /tmp/bat-v${BAT_VERSION}-* && \
+    bat --version
+
+# eza — modern ls replacement
+ARG EZA_VERSION=0.23.4
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://github.com/eza-community/eza/releases/download/v${EZA_VERSION}/eza_${ARCH}-unknown-linux-gnu.tar.gz" | tar -xz -C /usr/local/bin && \
+    eza --version | head -1
+
+# zoxide — smarter cd command
+ARG ZOXIDE_VERSION=0.9.9
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://github.com/ajeetdsouza/zoxide/releases/download/v${ZOXIDE_VERSION}/zoxide-${ZOXIDE_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
+    zoxide --version
+
+# uv — fast Python package manager (replaces pip, venv, pyenv)
+ARG UV_VERSION=0.11.7
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uv /usr/local/bin/uv && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uvx /usr/local/bin/uvx && \
+    rm -rf /tmp/uv-* && \
+    uv --version
+
+# rustup — Rust toolchain manager
+# Installs the rustup-init binary only. Users bootstrap Rust with:
+#   rustup-init -y && source ~/.cargo/env
+# Toolchains persist via devbox-rustup and devbox-cargo volumes.
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL "https://static.rust-lang.org/rustup/dist/${ARCH}-unknown-linux-gnu/rustup-init" -o /usr/local/bin/rustup-init && \
+    chmod +x /usr/local/bin/rustup-init
+
+# Set locale — generate common UTF-8 locales (override via LANG/LC_ALL env vars)
+# To add more locales, run: sudo sed -i '/<locale>.UTF-8/s/^# //g' /etc/locale.gen && sudo locale-gen
+RUN sed -i -E '/(en_US|en_GB|sv_SE|da_DK|nb_NO|fi_FI|de_DE|fr_FR|es_ES|it_IT|pt_BR|nl_NL|pl_PL|ja_JP|ko_KR|zh_CN)\.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
 ENV LANG=en_US.UTF-8
 ENV LANGUAGE=en_US:en
 ENV LC_ALL=en_US.UTF-8
+ENV EDITOR=nvim
+ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
 
 # ── Node.js (required for opencode v1.x install + MCP servers) ──────
 ARG NODE_VERSION=22
@@ -77,7 +157,7 @@ RUN if [ "${INSTALL_PYTHON}" = "true" ]; then \
 
 # ── Optional: Go ─────────────────────────────────────────────────────
 ARG INSTALL_GO=false
-ARG GO_VERSION=1.23.4
+ARG GO_VERSION=1.26.2
 RUN if [ "${INSTALL_GO}" = "true" ]; then \
       GOARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
       curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-${GOARCH}.tar.gz" | tar -C /usr/local -xz && \
@@ -85,6 +165,29 @@ RUN if [ "${INSTALL_GO}" = "true" ]; then \
       ln -s /usr/local/go/bin/gofmt /usr/local/bin/gofmt; \
     fi
 
+# ── Optional: oh-my-opencode-slim (multi-agent orchestration) ────────
+# Installs Bun runtime and the oh-my-opencode-slim npm package.
+# Runtime activation is controlled by ENABLE_OMOS env var in entrypoint.
+# Uses the baseline Bun build (SSE4.2 only) for compatibility with older
+# CPUs that lack AVX2 (e.g. Sandy Bridge on OpenStack).
+ARG INSTALL_OMOS=false
+ARG OMOS_VERSION=latest
+RUN if [ "${INSTALL_OMOS}" = "true" ]; then \
+      ARCH=$(uname -m) && \
+      if [ "$ARCH" = "x86_64" ]; then \
+        BUN_ARCH="x64-baseline"; \
+      elif [ "$ARCH" = "aarch64" ]; then \
+        BUN_ARCH="aarch64"; \
+      fi && \
+      curl -fsSL "https://github.com/oven-sh/bun/releases/latest/download/bun-linux-${BUN_ARCH}.zip" -o /tmp/bun.zip && \
+      unzip -o /tmp/bun.zip -d /tmp/bun && \
+      mv /tmp/bun/bun-linux-${BUN_ARCH}/bun /usr/local/bin/bun && \
+      chmod +x /usr/local/bin/bun && \
+      rm -rf /tmp/bun /tmp/bun.zip && \
+      bun --version && \
+      npm install -g oh-my-opencode-slim@${OMOS_VERSION}; \
+    fi
+
 # ── Non-root user ────────────────────────────────────────────────────
 ARG USER_NAME=developer
 ARG USER_UID=1000
@@ -99,9 +202,23 @@ RUN mkdir -p /workspace \
     /home/${USER_NAME}/.config/opencode/skills \
     /home/${USER_NAME}/.agents/skills \
     /home/${USER_NAME}/.local/share/opencode \
+    /home/${USER_NAME}/.cache/bash \
     /home/${USER_NAME}/.ssh && \
     chown -R ${USER_NAME}:${USER_NAME} /workspace /home/${USER_NAME}
 
+# ── Shell defaults (bash history, aliases, readline) ─────────────────
+# Shipped under /etc/skel-devbox/ rather than copied directly to the
+# user's home. The entrypoint copies them to /home/developer/ only if
+# the target file does not already exist, so host bind-mounts and
+# previously-customized files are never overwritten. Users can restore
+# the baked defaults anytime via:
+#   cp /etc/skel-devbox/.bash_aliases ~/.bash_aliases
+# History itself persists via the devbox-shell-history named volume
+# mounted at ~/.cache/bash (HISTFILE points there).
+RUN mkdir -p /etc/skel-devbox
+COPY rootfs/home/developer/.bash_aliases /etc/skel-devbox/.bash_aliases
+COPY rootfs/home/developer/.inputrc      /etc/skel-devbox/.inputrc
+
 # ── Entrypoint ────────────────────────────────────────────────────────
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY entrypoint-user.sh /usr/local/bin/entrypoint-user.sh

README.md

@@ -27,18 +27,33 @@ docker compose run --rm devbox
 
 ## Features
 
-- **Debian bookworm** base — glibc, full PTY/terminal support
+- **Debian trixie** base — glibc, full PTY/terminal support
 - **Configurable providers** — Anthropic, OpenAI, AWS Bedrock via env vars
 - **Host filesystem access** — bind mount any directory as `/workspace`
 - **SSH key forwarding** — git push/pull to private repos
 - **MCP server support** — Node.js included for `npx`-based MCP servers
 - **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
-- **Optional runtimes** — Python, Go via build args (Node.js always included — required for opencode v1.x)
+- **Python via uv** — `uv` package manager included; install Python on demand with `uv python install`
+- **Rust via rustup** — `rustup-init` included; bootstrap Rust on demand with `rustup-init -y`
+- **Optional runtimes** — Python (apt), Go via build args (Node.js always included — required for opencode v1.x)
+- **Multi-agent orchestration** — optional [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) integration via build arg
 - **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
 - **Multi-arch** — amd64 and arm64
 
 ## Usage
 
+### Prerequisites
+
+Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
+
+```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
 
 From your laptop, SSH into the remote server where Docker is running, then start the container:
@@ -76,10 +91,10 @@ docker compose run --rm devbox
 docker compose up -d
 
 # Attach a shell to the running container
-docker compose exec devbox bash
+docker compose exec -u developer devbox bash
 
 # Or run a single command inside it
-docker compose exec devbox aws --version
+docker compose exec -u developer devbox aws --version
 ```
 
 > `run` creates a new container (cleaned up with `--rm`). `exec` attaches to an already running one.
@@ -95,32 +110,208 @@ docker compose exec devbox aws --version
 | `ANTHROPIC_API_KEY` | Anthropic API key | — |
 | `OPENAI_API_KEY` | OpenAI API key | — |
 | `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
+| `AWS_PROFILE` | AWS SSO profile name | `default` |
 | `GIT_USER_NAME` | Git commit author name | — |
 | `GIT_USER_EMAIL` | Git commit author email | — |
 | `WORKSPACE_PATH` | Host path to mount | `.` |
 | `SSH_KEY_PATH` | Host SSH key directory | `~/.ssh` |
 | `USER_UID` | Override container user UID | Auto-detect from `/workspace` |
 | `USER_GID` | Override container user GID | Auto-detect from `/workspace` |
+| `LANG` | System locale | `en_US.UTF-8` |
+| `LANGUAGE` | Language priority list | `en_US:en` |
+| `LC_ALL` | Override all locale settings | `en_US.UTF-8` |
+| `EDITOR` | Default text editor | `nvim` |
+| `ENABLE_OMOS` | Enable oh-my-opencode-slim multi-agent orchestration | `false` |
+| `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` |
 
 ### Custom opencode config
 
-Mount your own `opencode.json` for full control (MCP servers, custom models, etc.):
+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:
 
 ```yaml
 volumes:
-  - ./my-opencode.json:/home/developer/.config/opencode/opencode.json:ro
+  - ~/.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.
+
 ### Custom skills
 
-Mount your host's opencode skills into the container:
+Mount agent skills from the host:
 
 ```yaml
 volumes:
-  - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
   - ~/.agents/skills:/home/developer/.agents/skills:ro
 ```
 
+### Neovim configuration
+
+The image includes neovim 0.12 with `EDITOR=nvim` set by default. To use your own neovim config (and have plugins auto-install via lazy.nvim on first start), mount it from the host:
+
+```yaml
+volumes:
+  - ~/.config/nvim:/home/developer/.config/nvim:ro
+```
+
+### Python development with uv
+
+The image includes Python 3.13 (from Debian Trixie) and [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv:
+
+```bash
+# Python 3.13 is available out of the box
+python3 --version
+
+# Use uv for package management
+uv venv
+uv pip install -r requirements.txt
+
+# Or use uv's project workflow (reads pyproject.toml)
+uv sync
+
+# Run a Python script
+uv run python script.py
+
+# Install standalone Python tools
+uvx ruff check .
+
+# Install a newer Python version (persists with devbox-uv volume)
+uv python install 3.14
+```
+
+Python installations are stored in `~/.local/share/uv/`. To persist them across container restarts, add the `devbox-uv` named volume to your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - devbox-uv:/home/developer/.local/share/uv
+
+volumes:
+  devbox-uv:
+```
+
+Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
+
+### Rust development with rustup
+
+The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
+
+```bash
+# One-time setup: install Rust toolchain (~300MB, persists with volumes)
+rustup-init -y
+source ~/.cargo/env
+
+# Now use Rust normally
+cargo new my-project
+cargo build
+cargo run
+```
+
+To persist Rust toolchains and cargo data across container restarts, add named volumes to your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - devbox-rustup:/home/developer/.rustup
+  - devbox-cargo:/home/developer/.cargo
+
+volumes:
+  devbox-rustup:
+  devbox-cargo:
+```
+
+### JavaScript and TypeScript
+
+The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
+
+```bash
+# Initialize a new project
+npm init -y
+
+# Install dependencies
+npm install
+
+# Run TypeScript (via tsx, ts-node, etc.)
+npx tsx src/index.ts
+
+# Use npx for one-off tools
+npx tsc --init
+```
+
+The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
+
+```bash
+bun init
+bun install
+bun run src/index.ts
+```
+
+Node modules are stored in your project directory under `/workspace` and persist automatically.
+
+### VS Code integration
+
+VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
+
+**Local Docker (Docker running on your workstation):**
+
+1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
+2. Start the container: `docker compose up -d`
+3. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
+
+**Remote Docker (Docker running on a remote server, e.g. via SSH):**
+
+1. Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extensions
+2. Connect to the remote host: `Ctrl+Shift+P` → "Remote-SSH: Connect to Host"
+3. On the remote host, start the container: `docker compose up -d`
+4. In VS Code (now connected to the remote): `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container"
+
+VS Code extensions installed inside the container persist as long as the container exists (not removed with `docker compose down`). For persistent extension storage across container recreations, add a named volume:
+
+```yaml
+volumes:
+  - devbox-vscode:/home/developer/.vscode-server
+```
+
+### Multi-user setup
+
+The shared-machine compose file (`docker-compose.shared.yml`) supports two modes:
+
+**Own-account mode** (each user has their own OS login — the common case):
+Leave `SIGNUM` unset in `.env`. The project name defaults to `devbox-$USER`, so each OS user automatically gets isolated container names and named volumes with zero configuration.
+
+**Shared-account mode** (everyone logs in as the same OS user, e.g. `garage`):
+Each user sets `SIGNUM=<unique-id>` in `.env` to get isolation.
+
+Setup per user:
+
+```bash
+# Replace <signum> with your username/identifier
+mkdir -p ~/<signum>/opencode-devbox
+cd ~/<signum>/opencode-devbox
+
+# Copy the shared-machine compose and env files
+cp /path/to/opencode-devbox/docker-compose.shared.yml docker-compose.yml
+cp /path/to/opencode-devbox/.env.shared.example .env
+
+# Create per-user config directory
+mkdir -p ~/<signum>/.config/opencode
+
+# Edit .env — set SIGNUM only if you're in shared-account mode
+vim .env
+
+# Start
+docker compose up -d
+docker compose exec -u developer devbox opencode
+```
+
+Each user's container, config, and named volumes are fully isolated:
+- Container name: `devbox-<signum>` (or `devbox-$USER` in own-account mode)
+- Named volumes: prefixed with the project name (`devbox-<signum>_devbox-data`, etc.) — the Docker daemon is system-wide, so directory-name prefixing alone is NOT sufficient for isolation
+- Opencode config: `~/<signum>/.config/opencode/` (per-user settings, OMOS config, etc.)
+
+See `docker-compose.shared.yml` and `.env.shared.example` for the full configuration.
+
 ### Rebuilding the Image
 
 `docker compose run` and `docker compose up` use the existing image — they **do not rebuild** when you change the Dockerfile or build args (e.g. updating `OPENCODE_VERSION`). Rebuild explicitly:
@@ -147,14 +338,100 @@ docker compose build --build-arg OPENCODE_VERSION=1.5.0
 |---|---|---|
 | `INSTALL_PYTHON` | `false` | Python 3 + pip + venv |
 | `INSTALL_GO` | `false` | Go toolchain |
+| `INSTALL_OMOS` | `false` | [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration (installs Bun and plugin) |
+| `OMOS_VERSION` | `latest` | Pin a specific oh-my-opencode-slim version |
+
+## oh-my-opencode-slim (Multi-Agent Orchestration)
+
+[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) adds a multi-agent layer on top of opencode — an Orchestrator delegates tasks to specialized agents (Explorer, Oracle, Librarian, Designer, Fixer), each configurable with different models and providers.
+
+### Setup
+
+A pre-built OMOS image is available on Docker Hub as `joakimp/opencode-devbox:latest-omos`. Alternatively, build from source:
+
+**1. Build the image with OMOS support:**
+
+```bash
+docker compose build --build-arg INSTALL_OMOS=true
+```
+
+This installs Bun and the oh-my-opencode-slim package into the image.
+
+**2. Enable in `.env`:**
+
+```bash
+ENABLE_OMOS=true
+```
+
+**3. Run as normal:**
+
+```bash
+docker compose run --rm devbox
+```
+
+On first start, the entrypoint runs the oh-my-opencode-slim installer in non-interactive mode. It generates agent configuration at `~/.config/opencode/oh-my-opencode-slim.json` inside the container. The default preset uses OpenAI models — edit the generated config or mount your own to customize.
+
+### OMOS Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `ENABLE_OMOS` | `false` | Activate oh-my-opencode-slim on container start |
+| `OMOS_TMUX` | `false` | Enable tmux pane integration (tmux is included in the base image) |
+| `OMOS_SKILLS` | `true` | Install recommended skills (simplify, agent-browser, cartography) |
+| `OMOS_RESET` | `false` | Force regenerate config on next start (backs up existing config) |
+
+### Custom Configuration
+
+If you mount the opencode config directory (see Custom opencode config above), the `oh-my-opencode-slim.json` file is included and persists across restarts. Edit it directly to control which models power each agent, fallback chains, council setup, and more.
+
+See the [oh-my-opencode-slim configuration docs](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/docs/configuration.md) for the full reference.
+
+### Verifying Agents
+
+After starting opencode with OMOS enabled, run inside the opencode session:
+
+```
+ping all agents
+```
+
+All six agents should respond if your provider authentication is working.
 
 ## AWS Bedrock Authentication
 
-When using AWS Bedrock as your LLM provider, you need to authenticate via AWS SSO from inside the container. Since the container runs headless (no browser), use the device-code flow:
+When using AWS Bedrock as your LLM provider, you need:
+
+### 1. AWS config on the host
+
+The container needs access to your `~/.aws/config` with SSO session configuration. If you already have this on another machine, copy it:
 
 ```bash
-# Start the container interactively
-docker compose run --rm devbox bash
+scp -r user@other-machine:~/.aws ~/.aws
+```
+
+Or configure from scratch on the host:
+
+```bash
+aws configure sso
+```
+
+### 2. Mount `~/.aws` into the container
+
+Uncomment the AWS volume mount in `docker-compose.yml`:
+
+```yaml
+- ~/.aws:/home/developer/.aws
+```
+
+Note: do **not** use `:ro` — SSO writes token cache files to this directory.
+
+### 3. Authenticate inside the container
+
+Since the container runs headless (no browser), use the device-code flow:
+
+```bash
+# Start the container
+docker compose up -d
+docker compose exec -u developer devbox bash
 
 # Authenticate — prints a URL and code you open in your local browser
 aws sso login --sso-session <your-sso-session> --use-device-code
@@ -165,7 +442,52 @@ opencode
 
 The `--use-device-code` flag outputs a URL and short code instead of trying to open a browser. Copy the URL into any browser (on your laptop, phone, etc.), enter the code, and complete the 2FA flow. The CLI in the container picks up the session automatically.
 
-SSO sessions typically last 8–12 hours before requiring re-authentication.
+SSO sessions typically last 8–12 hours before requiring re-authentication. Since `~/.aws` is mounted from the host, tokens persist across container restarts.
+
+## 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
+```
 
 ## Secret Scanning
 
@@ -201,14 +523,18 @@ Allowlisted paths and rules are in `.gitleaks.toml`. The defaults extend gitleak
 Host Machine
 ├── ~/projects/my-app  ──bind mount──▶  /workspace (container)
 ├── ~/.ssh             ──bind mount──▶  /home/developer/.ssh (ro)
+├── ~/.aws             ──bind mount──▶  /home/developer/.aws (Bedrock SSO)
 └── .env               ──env vars───▶  provider config + API keys
 
-Container (Debian bookworm)
+Container (Debian trixie)
 ├── opencode binary
+├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
 ├── AWS CLI v2 (SSO + Bedrock auth)
-├── git, ssh, ripgrep, fd, jq, curl, fzf
+├── neovim 0.12, tmux, htop, bat, eza, zoxide, uv, rustup, make, gcc, g++, rsync
+├── git, git-crypt, age, ssh, ripgrep, fd, fzf, jq, curl, tree
 ├── Node.js (for MCP servers)
-├── entrypoint.sh (SSH perms, git config, provider setup)
+├── Bun (optional — included with oh-my-opencode-slim)
+├── entrypoint.sh (UID adjustment, git config, provider setup)
 └── /workspace ← your code lives here
 ```
 
@@ -218,13 +544,19 @@ Container (Debian bookworm)
 |---|---|---|---|
 | `/workspace` | Host bind mount | ✅ Yes | Your project files |
 | `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
+| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes | AWS credentials/SSO cache |
 | `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
-| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No | Provider/model config |
-| `/home/developer/.aws` | Not mounted by default | ❌ No | AWS SSO tokens |
+| `/home/developer/.local/state/opencode` | Named volume `devbox-state` | ✅ Yes | TUI settings (theme, toggles) |
+| `/home/developer/.cache/bash` | Named volume `devbox-shell-history` | ✅ Yes | Bash history (`$HISTFILE`), survives container recreate |
+| `/home/developer/.local/share/zoxide` | Named volume `devbox-zoxide` | ✅ Yes | Zoxide directory history (`z <fragment>` jump targets) |
+| `/home/developer/.local/share/nvim` | Named volume `devbox-nvim-data` | ✅ Yes | Neovim plugins, Mason LSP installs, Lazy plugin cache |
+| `/home/developer/.local/share/uv` | Named volume `devbox-uv` (if configured) | ✅ Yes | Python installs, uv tool installs |
+| `/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 |
 
-**opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To use MCP servers or custom settings, mount your own config file (see Custom opencode config above).
-
-To persist AWS SSO sessions across restarts, uncomment the `~/.aws` volume mount in `docker-compose.yml`.
+**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).
 
 ## License
 

check-versions.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# check-versions.sh — Compare pinned versions in Dockerfile against latest releases
+# Run before tagging a release to see what can be bumped.
+set -euo pipefail
+
+BOLD="\033[1m"; DIM="\033[2m"; GREEN="\033[32m"; YELLOW="\033[33m"; RESET="\033[0m"
+
+DOCKERFILE="${1:-Dockerfile}"
+
+if [[ ! -f "$DOCKERFILE" ]]; then
+  echo "Usage: $0 [Dockerfile]"
+  exit 1
+fi
+
+get_pinned() {
+  grep "^ARG $1=" "$DOCKERFILE" | head -1 | cut -d= -f2
+}
+
+get_latest_github() {
+  local repo="$1"
+  local tag
+  tag=$(curl -s "https://api.github.com/repos/${repo}/releases/latest" | jq -r '.tag_name // empty')
+  # Strip leading 'v' if present
+  echo "${tag#v}"
+}
+
+get_latest_go() {
+  curl -s "https://go.dev/dl/?mode=json" | jq -r '.[0].version' | sed 's/^go//'
+}
+
+get_latest_npm() {
+  npm view "$1" version 2>/dev/null
+}
+
+check() {
+  local name="$1" current="$2" latest="$3"
+  if [[ -z "$latest" ]]; then
+    printf "  ${DIM}%-20s %-12s  (could not check)${RESET}\n" "$name" "$current"
+  elif [[ "$current" == "$latest" ]]; then
+    printf "  ${GREEN}%-20s %-12s  ✓ up to date${RESET}\n" "$name" "$current"
+  else
+    printf "  ${YELLOW}${BOLD}%-20s %-12s  → %s available${RESET}\n" "$name" "$current" "$latest"
+  fi
+}
+
+echo ""
+echo -e "${BOLD}Version check for $DOCKERFILE${RESET}"
+echo ""
+
+# GitHub-sourced binaries
+check "opencode"  "$(get_pinned OPENCODE_VERSION)" "$(get_latest_npm opencode-ai)"
+check "gosu"      "$(get_pinned GOSU_VERSION)"      "$(get_latest_github tianon/gosu)"
+check "fzf"       "$(get_pinned FZF_VERSION)"        "$(get_latest_github junegunn/fzf)"
+check "git-lfs"   "$(get_pinned GIT_LFS_VERSION)"    "$(get_latest_github git-lfs/git-lfs)"
+check "neovim"    "$(get_pinned NVIM_VERSION)"        "$(get_latest_github neovim/neovim)"
+check "bat"       "$(get_pinned BAT_VERSION)"         "$(get_latest_github sharkdp/bat)"
+check "eza"       "$(get_pinned EZA_VERSION)"         "$(get_latest_github eza-community/eza)"
+check "zoxide"    "$(get_pinned ZOXIDE_VERSION)"      "$(get_latest_github ajeetdsouza/zoxide)"
+check "uv"        "$(get_pinned UV_VERSION)"          "$(get_latest_github astral-sh/uv)"
+check "Go (opt)"  "$(get_pinned GO_VERSION)"          "$(get_latest_go)"
+
+echo ""
+echo -e "${DIM}Node.js uses major version ($(get_pinned NODE_VERSION)) — auto-updates via nodesource.${RESET}"
+echo -e "${DIM}rustup-init uses latest from static.rust-lang.org — no pinned version.${RESET}"
+echo -e "${DIM}Debian apt packages update on each build via apt-get update.${RESET}"
+echo ""

deploy/README.md

@@ -0,0 +1,318 @@
+# Deploy — Host VM setup
+
+Scripts for setting up a fresh Linux VM to host opencode-devbox.
+
+## Files
+
+- **`cloud-init.yml`** — cloud-init user-data template for automated VM provisioning on OpenStack, Proxmox, or any cloud with cloud-init support
+- **`setup-host.sh`** — interactive post-install script for VMs that weren't provisioned with cloud-init
+- **`setup-openstack-secgroup.sh`** — creates an OpenStack security group with the right rules (SSH, mosh, ICMP)
+- **`sync-to-vm.sh`** — syncs local config directories (`~/.aws`, `~/.config/opencode`, etc.) to a remote VM based on which bind mounts are active in its `docker-compose.yml`
+
+## Supported distributions
+
+- **Debian 13 (Trixie)** — recommended (matches opencode-devbox base image)
+- **Ubuntu 24.04 LTS** — also works
+
+Other distributions will need manual adaptation.
+
+## Quick start
+
+### Option 1: Cloud-init (automated)
+
+Customize `cloud-init.yml` — replace the SSH public key and optionally the hostname/timezone. Then use it during VM creation:
+
+- **Proxmox**: attach as cloud-init user-data
+- **OpenStack**: pass via `--user-data` flag (see full example below)
+- **AWS/DigitalOcean/etc**: paste into the "user data" field
+
+#### Full OpenStack example
+
+Cloud-init only handles guest configuration — flavor, image, network, and security group must be specified explicitly at creation time.
+
+> **Note:** Do not use `--key-name` — the SSH key is configured in `cloud-init.yml` under `ssh_authorized_keys` for the `devbox` user. The `--key-name` flag injects into the image's default user (e.g. `debian`), not the `devbox` user created by cloud-init.
+
+```bash
+# List available flavors to choose appropriate sizing
+openstack flavor list
+
+# Create the security group first (one-time, see below)
+./setup-openstack-secgroup.sh
+
+# Basic — boot from default storage
+openstack server create \
+  --flavor c4m8 \
+  --image Debian-13-Trixie \
+  --network my-network \
+  --security-group opencode-devbox \
+  --user-data cloud-init.yml \
+  devbox-vm
+```
+
+If your cloud offers NVMe-backed (performance) volumes, boot from one for faster Docker and build I/O:
+
+```bash
+# Performance — boot from NVMe volume (40GB, preserved on instance deletion)
+openstack server create \
+  --flavor c4m8 \
+  --network my-network \
+  --security-group opencode-devbox \
+  --user-data cloud-init.yml \
+  --block-device source_type=image,uuid=$(openstack image show Debian-13-Trixie -f value -c id),destination_type=volume,volume_size=40,delete_on_termination=false,boot_index=0,volume_type=performance \
+  devbox-vm
+```
+
+> **Note:** The inline `volume_type` parameter requires API microversion 2.67+. If the server goes to ERROR state, check your volume quota (`openstack quota show`) and try creating the volume separately:
+> ```bash
+> openstack volume create --image Debian-13-Trixie --size 40 --type performance --bootable devbox-boot-volume
+> openstack server create --flavor c4m8 --volume devbox-boot-volume --network my-network --security-group opencode-devbox --user-data cloud-init.yml devbox-vm
+> ```
+
+#### Floating IP
+
+OpenStack doesn't support assigning a floating IP at instance creation time — it's a separate step after the VM is active:
+
+```bash
+# Allocate a new floating IP from the external network
+openstack floating ip create <external-network>
+
+# Assign it to the VM
+openstack server add floating ip devbox-vm <floating-ip>
+```
+
+To find your external network name: `openstack network list --external`. If you already have an unassigned floating IP, skip the create step.
+
+The VM boots with Docker installed, firewall configured (or skipped on OpenStack), and your SSH key authorized. Log in as the `devbox` user.
+
+### Console password (optional)
+
+The cloud-init template uses SSH key authentication only — no password is set by default. This is sufficient for normal use since the `devbox` user has passwordless `sudo`.
+
+A password is only needed for:
+
+- **Emergency console access** — logging in via OpenStack Horizon console (noVNC) or Proxmox VNC when SSH is unreachable
+- **`su - devbox`** — switching to the devbox user from another account
+
+To enable console access, uncomment the `chpasswd` block in `cloud-init.yml` before deploying:
+
+```yaml
+chpasswd:
+  expire: false
+  users:
+    - name: devbox
+      password: your-password-here
+      type: text
+```
+
+For an already-running VM, set a password via SSH:
+
+```bash
+sudo passwd devbox
+```
+
+### Option 2: Post-install script (manual)
+
+On a fresh Debian/Ubuntu VM:
+
+```bash
+curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/deploy/setup-host.sh | bash
+```
+
+Or clone and run:
+
+```bash
+git clone https://gitea.jordbo.se/joakimp/opencode-devbox
+cd opencode-devbox/deploy
+./setup-host.sh
+```
+
+## What gets installed
+
+- Docker Engine (from Docker's official apt repo, not distro's `docker.io`)
+- Docker Compose plugin (v2)
+- `tmux`, `mosh`, `git`
+- `ufw` firewall with SSH (22) and mosh (UDP 60000-61000) allowed — **skipped on OpenStack** (detected automatically; use security groups instead)
+- IPv4 DNS preference (works around Docker Hub IPv6 connectivity issues)
+
+## OpenStack security groups
+
+On OpenStack, firewalling is handled by security groups rather than ufw. The `setup-host.sh` script detects OpenStack automatically and skips ufw configuration.
+
+To create the required security group:
+
+```bash
+./setup-openstack-secgroup.sh
+```
+
+This creates a security group named `opencode-devbox` with rules for SSH (TCP 22), mosh (UDP 60000-61000), and ICMP. Apply it to your instance:
+
+```bash
+# New instance
+openstack server create --security-group opencode-devbox ...
+
+# Existing instance
+openstack server add security group <instance-name> opencode-devbox
+```
+
+## VM sizing recommendations
+
+| Use case | vCPU | RAM | Disk |
+|---|---|---|---|
+| Minimum | 2 | 4 GB | 20 GB |
+| Recommended | 4 | 8 GB | 40 GB |
+| Heavy use (Rust/Python builds, multi-project) | 8 | 16 GB | 80 GB |
+
+## After VM setup
+
+If you uncomment any bind mounts in `docker-compose.yml` (e.g. `~/.aws`, `~/.config/opencode`), create the directories first — Docker creates missing bind mount paths as root-owned, which causes permission issues:
+
+```bash
+# Only create directories for mounts you uncomment
+mkdir -p ~/.aws                  # AWS Bedrock SSO
+mkdir -p ~/.config/opencode      # persistent opencode config
+mkdir -p ~/.config/nvim          # custom neovim config
+mkdir -p ~/.agents/skills        # opencode agent skills
+```
+
+Named volumes (`devbox-data`, `devbox-uv`, etc.) are managed by Docker and need no pre-creation.
+
+```bash
+mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml -o docker-compose.yml
+curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+vim .env                                           # configure provider and keys
+vim docker-compose.yml                             # uncomment optional volume mounts
+docker compose up -d
+docker compose exec -u developer devbox opencode
+```
+
+> **AWS Bedrock users:** Uncomment the `~/.aws` volume mount in `docker-compose.yml` before starting. You'll also need to copy your `~/.aws/config` from a machine where SSO is already configured, then authenticate inside the container with `aws sso login`.
+
+### Syncing local config to the VM
+
+After editing `docker-compose.yml` on the VM to uncomment the bind mounts you need, run `sync-to-vm.sh` from your local machine to copy the corresponding directories:
+
+```bash
+./deploy/sync-to-vm.sh devbox-affection
+```
+
+The script reads `docker-compose.yml` on the remote VM, detects which bind mounts are active, and syncs only those directories from your local machine. It also creates the remote directories if they don't exist.
+
+### Upgrading an existing VM to a new release
+
+Each tagged release may add new named volumes or bind-mount lines to `docker-compose.yml`. Pulling a new image via `docker compose pull` grabs the new container behaviour, but compose files on the VM are user-owned and never touched by the image — you have to reconcile them yourself when upgrading across versions.
+
+**Symptom of a missed reconcile:** a new feature quietly doesn't work even though the image is correct. Example from v1.14.19c → v1.14.20: bash history persistence requires the `devbox-shell-history` named volume mounted at `/home/developer/.cache/bash`. The v1.14.20 image writes history to that path either way, but without the volume mount on the VM, writes land in the container's writable layer and vanish on every `--force-recreate`.
+
+**Upgrade ritual:**
+
+```bash
+# On the VM, before recreating the container:
+cd ~/opencode-devbox
+cp docker-compose.yml docker-compose.yml.bak-$(date +%Y%m%d-%H%M%S)
+
+# Compare against the repo version to see what's new:
+#   (from your local checkout)
+scp devbox-affection:~/opencode-devbox/docker-compose.yml /tmp/vm-compose.yml
+diff -u /tmp/vm-compose.yml ~/src/src_local/opencode-devbox/docker-compose.yml
+```
+
+For each new `volumes:` entry or mount line in the repo version that isn't in your VM's file, add it manually — preserving any local customizations you've made (image variant, read/write flags on bind mounts, etc.). Then:
+
+```bash
+docker compose config >/dev/null   # verify YAML still parses
+docker compose up -d --force-recreate
+```
+
+If you maintain the VM's compose file with no local changes, `scp` the repo version over wholesale. If you have customizations (the common case), do the diff-and-merge by hand.
+
+### Shell defaults inside the container
+
+The image ships baked `.bash_aliases` and `.inputrc` in `/etc/skel-devbox/` — quality-of-life defaults (prefix history search on Up/Down arrows, persistent history across container recreates via the `devbox-shell-history` named volume, `[devbox]` prompt marker, sensible aliases). On first container start the entrypoint copies them to `/home/developer/` **only if the target file does not already exist**.
+
+This means:
+
+- Fresh containers get the defaults automatically.
+- If you bind-mount your host's `~/.bash_aliases` / `~/.inputrc` (see the commented lines in `docker-compose.yml`), your host versions win.
+- If you edit the files inside a running container and store them via a home-dir bind-mount or equivalent, subsequent upgrades never overwrite them.
+- To restore the baked defaults any time: `cp /etc/skel-devbox/.bash_aliases ~/` (or delete the file and recreate the container).
+- To diff your current config against what the image ships: `diff ~/.bash_aliases /etc/skel-devbox/.bash_aliases`.
+
+### CI runner maintenance: automatic Docker pruning
+
+Gitea Actions runners accumulate Docker build cache, stale buildkit containers, and unused images over time. Without periodic cleanup, the runner's disk fills up and builds stall during the image-push phase (symptom: `#61 exporting to image` / `pushing layers` hangs indefinitely while buildkit repeatedly re-authenticates with Docker Hub).
+
+Set up two layers of automatic cleanup on the runner host:
+
+**1. Daily cron job** — prunes images, containers, and build cache older than 72 hours:
+
+```bash
+sudo tee /etc/cron.daily/docker-prune <<'EOF'
+#!/bin/sh
+docker system prune -af --filter "until=72h" > /var/log/docker-prune.log 2>&1
+docker builder prune -af --filter "until=72h" >> /var/log/docker-prune.log 2>&1
+EOF
+sudo chmod +x /etc/cron.daily/docker-prune
+```
+
+**2. Docker daemon builder GC** — caps buildkit cache at 10 GB (Docker 23.0+):
+
+Add to `/etc/docker/daemon.json` (create if absent):
+
+```json
+{
+  "builder": {
+    "gc": {
+      "enabled": true,
+      "defaultKeepStorage": "10GB"
+    }
+  }
+}
+```
+
+Then `sudo systemctl restart docker`.
+
+Both are safe to run on a machine that also hosts long-running containers (like opencode-devbox) — `docker system prune` only removes *unused* images and *stopped* containers, never running ones.
+
+### Troubleshooting: SSH hangs or "banner exchange" timeouts
+
+If SSH to the VM intermittently fails with `Connection timed out during banner exchange` or pure TCP connect timeouts — especially after the first few successful connects in a short window — the cause is almost certainly your ISP's CGNAT (Carrier-Grade NAT), not the VM.
+
+**Symptoms**
+
+- First 3–4 SSH connects succeed, then subsequent ones fail hard for 20–30 minutes
+- `ping` to the VM works perfectly throughout (ICMP isn't tracked the same way)
+- `mosh` sessions stay stable once established (UDP, different flow table)
+- Happens on residential ISPs (Tele2, Comhem, Telia, most European consumer broadband)
+- VM-side logs show SSH is idle — the SYNs never reach it
+
+**Cause**
+
+Residential CGNAT boxes keep a per-subscriber TCP flow table with a small concurrent-flow cap (~4) per destination IP. Once exhausted, new SYNs to that destination are silently dropped until old flows age out (typically 20–30 min after TCP close).
+
+**Fix**
+
+Add SSH connection multiplexing on your client so all SSH sessions (interactive, `scp`, `rsync`, scripts) share a single TCP connection to the VM:
+
+```ssh-config
+# ~/.ssh/config
+Host <vm-alias>
+    HostName <vm-ip>
+    User devbox
+    IdentityFile ~/.ssh/id_ed25519
+    ControlMaster auto
+    ControlPath ~/.ssh/cm/%r@%h:%p
+    ControlPersist 4h
+    ServerAliveInterval 30
+    ServerAliveCountMax 6
+```
+
+Then create the socket directory:
+
+```bash
+mkdir -p ~/.ssh/cm && chmod 700 ~/.ssh/cm
+```
+
+All SSH to the VM now multiplexes over a single flow slot, regardless of how many parallel sessions you open. `sync-to-vm.sh` already does this internally for its own rsync/scp calls.
+
+For a more robust long-term fix (especially if you access the VM from multiple hosts), run a WireGuard tunnel on the VM and route SSH through that — UDP bypasses the TCP flow table entirely.

deploy/cloud-init.yml

@@ -0,0 +1,110 @@
+#cloud-config
+# cloud-init template for opencode-devbox host VM
+# Tested on Debian 13 (Trixie) and Ubuntu 24.04
+#
+# Usage:
+#   - Proxmox: attach this file as cloud-init user-data in VM config
+#   - OpenStack: pass as --user-data when creating the instance
+#   - Cloud providers: paste into "user data" field
+#
+# Customize the marked sections before use.
+
+# ── Hostname ─────────────────────────────────────────────────────────
+hostname: devbox
+manage_etc_hosts: true
+
+# ── User ─────────────────────────────────────────────────────────────
+users:
+  - name: devbox
+    groups: sudo, docker
+    shell: /bin/bash
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    ssh_authorized_keys:
+      # CUSTOMIZE: replace with your public SSH key.
+      # This is the only SSH key config needed — do NOT use --key-name with
+      # openstack server create, as that injects into the image's default
+      # user (e.g. debian), not the devbox user defined here.
+      - ssh-ed25519 AAAA... your-key-here
+
+# ── Optional: console password ───────────────────────────────────────
+# Uncomment to set a password for the devbox user. Only needed for
+# emergency access via the OpenStack/Proxmox console (VNC/noVNC).
+# SSH key authentication is used for normal access.
+#
+# chpasswd:
+#   expire: false
+#   users:
+#     - name: devbox
+#       password: your-password-here
+#       type: text
+
+# ── Locale and timezone ──────────────────────────────────────────────
+# en_US.UTF-8 is pre-generated on Debian/Ubuntu and works out of the box.
+# To use a different locale (e.g. sv_SE.UTF-8), add it to the runcmd
+# section before the locale is applied:
+#   - locale-gen sv_SE.UTF-8
+# Then change the locale line below to match.
+locale: en_US.UTF-8
+timezone: Europe/Stockholm
+
+# ── Package installation ─────────────────────────────────────────────
+package_update: true
+package_upgrade: true
+packages:
+  - ca-certificates
+  - curl
+  - gnupg
+  - git
+  - tmux
+  - mosh
+  - rsync
+  - fzf
+  - ripgrep
+  - ufw
+
+# ── Commands to run at first boot ────────────────────────────────────
+runcmd:
+  # Install Docker from official repository
+  - install -m 0755 -d /etc/apt/keyrings
+  - curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
+  - chmod a+r /etc/apt/keyrings/docker.asc
+  - echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo \"$ID\") $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" > /etc/apt/sources.list.d/docker.list
+  - apt-get update
+  - apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+  - usermod -aG docker devbox
+
+  # Firewall — skip on OpenStack (use security groups instead)
+  - |
+    if curl -s --connect-timeout 2 http://169.254.169.254/openstack/ >/dev/null 2>&1; then
+      echo "OpenStack detected — skipping ufw (use security groups instead)"
+    else
+      ufw default deny incoming
+      ufw default allow outgoing
+      ufw allow ssh
+      ufw allow 60000:61000/udp
+      ufw --force enable
+    fi
+
+  # Disable IPv6 preference for Docker (avoids intermittent Docker Hub connectivity issues)
+  - echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+  # Create projects directory for the user
+  - mkdir -p /home/devbox/projects
+  - chown devbox:devbox /home/devbox/projects
+
+# ── Final message ───────────────────────────────────────────────────
+final_message: |
+  opencode-devbox host VM ready.
+
+  Next steps:
+    1. SSH in:      ssh devbox@<this-host>
+    2. Clone your opencode-devbox compose config, or:
+       mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml -o docker-compose.yml
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+    3. Edit .env with your provider and keys
+    4. Edit docker-compose.yml to uncomment optional mounts (e.g. ~/.aws for Bedrock)
+    5. docker compose up -d
+    6. docker compose exec -u developer devbox opencode
+
+  Cloud-init run completed in $UPTIME seconds.

deploy/setup-host.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# setup-host.sh — Post-install script for opencode-devbox host VM
+#
+# Run this on a fresh Debian 13 or Ubuntu 24.04 VM to set up everything
+# needed to run opencode-devbox containers.
+#
+# Usage:
+#   curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/deploy/setup-host.sh | bash
+#
+# Or clone and run:
+#   git clone https://gitea.jordbo.se/joakimp/opencode-devbox
+#   cd opencode-devbox/deploy
+#   ./setup-host.sh
+
+set -euo pipefail
+
+# ── Colors ──────────────────────────────────────────────────────────
+BOLD="\033[1m"; GREEN="\033[32m"; YELLOW="\033[33m"; RED="\033[31m"; RESET="\033[0m"
+info()  { echo -e "${BOLD}==>${RESET} $*"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $*"; }
+err()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+# ── Detect distro ──────────────────────────────────────────────────
+if [[ ! -f /etc/os-release ]]; then
+  err "Cannot detect Linux distribution — /etc/os-release missing"
+  exit 1
+fi
+
+. /etc/os-release
+
+case "$ID" in
+  debian|ubuntu)
+    info "Detected $PRETTY_NAME"
+    ;;
+  *)
+    err "Unsupported distribution: $ID — this script only supports Debian and Ubuntu"
+    exit 1
+    ;;
+esac
+
+# ── Require sudo ────────────────────────────────────────────────────
+if [[ $EUID -eq 0 ]]; then
+  err "Do not run as root — use a regular user with sudo"
+  exit 1
+fi
+
+if ! sudo -n true 2>/dev/null; then
+  warn "This script needs sudo access. You may be prompted for your password."
+fi
+
+# ── Update packages ─────────────────────────────────────────────────
+info "Updating package index..."
+sudo apt-get update -qq
+
+info "Installing base packages..."
+sudo apt-get install -y --no-install-recommends \
+  ca-certificates curl gnupg git tmux mosh rsync fzf ripgrep ufw
+
+# ── Docker ──────────────────────────────────────────────────────────
+if command -v docker &>/dev/null; then
+  ok "Docker already installed ($(docker --version))"
+else
+  info "Installing Docker from official repository..."
+  sudo install -m 0755 -d /etc/apt/keyrings
+  sudo curl -fsSL "https://download.docker.com/linux/${ID}/gpg" -o /etc/apt/keyrings/docker.asc
+  sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | \
+    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+  sudo apt-get update -qq
+  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+
+  ok "Docker installed: $(docker --version)"
+fi
+
+# ── Add user to docker group ────────────────────────────────────────
+if groups | grep -q docker; then
+  ok "User already in docker group"
+else
+  info "Adding $USER to docker group..."
+  sudo usermod -aG docker "$USER"
+  warn "You must log out and back in for docker group to take effect"
+  warn "Or run: newgrp docker"
+fi
+
+# ── Firewall ────────────────────────────────────────────────────────
+# Detect OpenStack — if running on OpenStack, skip ufw (security groups handle firewalling)
+SKIP_UFW=false
+if curl -s --connect-timeout 2 http://169.254.169.254/openstack/ &>/dev/null; then
+  SKIP_UFW=true
+  warn "OpenStack detected — skipping ufw (use security groups instead)"
+  warn "Ensure your security group allows: SSH (22/tcp), mosh (60000-61000/udp)"
+fi
+
+if [[ "$SKIP_UFW" == "false" ]]; then
+  info "Configuring firewall (ufw)..."
+  sudo ufw default deny incoming >/dev/null
+  sudo ufw default allow outgoing >/dev/null
+  sudo ufw allow ssh >/dev/null
+  sudo ufw allow 60000:61000/udp comment 'mosh' >/dev/null
+  if ! sudo ufw status | grep -q "Status: active"; then
+    sudo ufw --force enable
+  fi
+  ok "Firewall active — SSH and mosh allowed"
+fi
+
+# ── IPv4 preference for Docker Hub ──────────────────────────────────
+if ! grep -q 'precedence ::ffff:0:0/96' /etc/gai.conf 2>/dev/null; then
+  info "Setting IPv4 preference in /etc/gai.conf..."
+  echo 'precedence ::ffff:0:0/96  100' | sudo tee -a /etc/gai.conf > /dev/null
+  ok "IPv4 preferred for DNS resolution"
+fi
+
+# ── Create projects directory ───────────────────────────────────────
+if [[ ! -d "$HOME/projects" ]]; then
+  mkdir -p "$HOME/projects"
+  ok "Created ~/projects"
+fi
+
+# ── Done ────────────────────────────────────────────────────────────
+echo ""
+ok "Host setup complete"
+echo ""
+cat <<EOF
+${BOLD}Next steps:${RESET}
+
+  1. If you weren't already in the docker group, log out and back in:
+       exit
+       ssh <your-user>@<this-host>
+
+  2. Set up opencode-devbox:
+       mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml -o docker-compose.yml
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+
+  3. Edit .env with your provider and API keys:
+       vim .env
+
+  4. Start and connect:
+       docker compose up -d
+       docker compose exec -u developer devbox opencode
+
+EOF

deploy/setup-openstack-secgroup.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# setup-openstack-secgroup.sh — Create an OpenStack security group for opencode-devbox
+#
+# Prerequisites:
+#   - OpenStack CLI installed (pip install python-openstackclient)
+#   - Authenticated (source your openrc.sh or clouds.yaml configured)
+#
+# Usage:
+#   ./setup-openstack-secgroup.sh [group-name]
+#
+# Default group name: opencode-devbox
+
+set -euo pipefail
+
+GROUP_NAME="${1:-opencode-devbox}"
+
+BOLD="\033[1m"; GREEN="\033[32m"; YELLOW="\033[33m"; RESET="\033[0m"
+info()  { echo -e "${BOLD}==>${RESET} $*"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $*"; }
+
+if ! command -v openstack &>/dev/null; then
+  echo "Error: openstack CLI not found. Install with: pip install python-openstackclient"
+  exit 1
+fi
+
+# Check if group already exists
+if openstack security group show "$GROUP_NAME" &>/dev/null; then
+  warn "Security group '$GROUP_NAME' already exists — updating rules"
+else
+  info "Creating security group '$GROUP_NAME'..."
+  openstack security group create "$GROUP_NAME" \
+    --description "opencode-devbox: SSH, mosh, HTTPS"
+  ok "Security group created"
+fi
+
+# Add rules (idempotent — OpenStack ignores duplicates)
+info "Adding rules..."
+
+# SSH (TCP 22)
+openstack security group rule create "$GROUP_NAME" \
+  --protocol tcp --dst-port 22 --remote-ip 0.0.0.0/0 \
+  --description "SSH" 2>/dev/null && ok "SSH (TCP 22)" || warn "SSH rule already exists"
+
+# Mosh (UDP 60000-61000)
+openstack security group rule create "$GROUP_NAME" \
+  --protocol udp --dst-port 60000:61000 --remote-ip 0.0.0.0/0 \
+  --description "mosh" 2>/dev/null && ok "mosh (UDP 60000-61000)" || warn "mosh rule already exists"
+
+# ICMP (ping — useful for diagnostics)
+openstack security group rule create "$GROUP_NAME" \
+  --protocol icmp --remote-ip 0.0.0.0/0 \
+  --description "ICMP ping" 2>/dev/null && ok "ICMP ping" || warn "ICMP rule already exists"
+
+echo ""
+ok "Security group '$GROUP_NAME' ready"
+echo ""
+echo -e "${BOLD}Apply to a new instance:${RESET}"
+echo "  openstack server create --security-group $GROUP_NAME ..."
+echo ""
+echo -e "${BOLD}Apply to an existing instance:${RESET}"
+echo "  openstack server add security group <instance-name> $GROUP_NAME"
+echo ""

deploy/sync-to-vm.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# sync-to-vm.sh — Copy local config to an opencode-devbox VM
+#
+# Reads docker-compose.yml on the remote VM to detect which bind mounts
+# are active, then syncs the corresponding directories from this machine.
+#
+# Usage:
+#   ./sync-to-vm.sh <ssh-host>
+#
+# Examples:
+#   ./sync-to-vm.sh devbox-affection
+#   ./sync-to-vm.sh devbox@129.192.68.184
+
+set -euo pipefail
+
+# ── Colors ──────────────────────────────────────────────────────────
+BOLD="\033[1m"; GREEN="\033[32m"; YELLOW="\033[33m"; RED="\033[31m"; RESET="\033[0m"
+info()  { echo -e "${BOLD}==>${RESET} $*"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $*"; }
+err()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+# ── Args ────────────────────────────────────────────────────────────
+if [[ $# -lt 1 ]]; then
+  err "Usage: $0 <ssh-host>"
+  echo "  Example: $0 devbox-affection"
+  exit 1
+fi
+
+SSH_HOST="$1"
+REMOTE_COMPOSE="~/opencode-devbox/docker-compose.yml"
+
+# ── SSH multiplexing (reuse one connection for all operations) ──────
+CTRL_SOCKET=$(mktemp -u /tmp/sync-to-vm-XXXXXX)
+SSH_OPTS="-o ControlMaster=auto -o ControlPath=${CTRL_SOCKET} -o ControlPersist=120 -o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=3"
+
+cleanup() {
+  ssh ${SSH_OPTS} -O exit "$SSH_HOST" 2>/dev/null || true
+  rm -f "$CTRL_SOCKET"
+}
+trap cleanup EXIT
+
+ssh_cmd() {
+  ssh ${SSH_OPTS} "$SSH_HOST" "$@"
+}
+
+# ── Bind mount patterns to detect ──────────────────────────────────
+# Maps: grep pattern → local source → remote destination
+declare -a MOUNT_PATTERNS=(
+  "~/.aws:/home/developer/.aws|$HOME/.aws|~/.aws"
+  "~/.config/opencode:/home/developer/.config/opencode|$HOME/.config/opencode|~/.config/opencode"
+  "~/.config/nvim:/home/developer/.config/nvim|$HOME/.config/nvim|~/.config/nvim"
+  "~/.agents/skills:/home/developer/.agents/skills|$HOME/.agents/skills|~/.agents/skills"
+)
+
+# ── Establish persistent SSH connection ─────────────────────────────
+info "Connecting to ${SSH_HOST}..."
+if ! ssh_cmd true 2>/dev/null; then
+  err "Cannot connect to ${SSH_HOST}"
+  exit 1
+fi
+ok "Connected to ${SSH_HOST}"
+
+# ── Fetch remote docker-compose.yml ─────────────────────────────────
+info "Reading docker-compose.yml from ${SSH_HOST}..."
+REMOTE_COMPOSE_CONTENT=$(ssh_cmd "cat $REMOTE_COMPOSE 2>/dev/null") || {
+  err "Could not read ${REMOTE_COMPOSE} on ${SSH_HOST}"
+  err "Has the VM been set up? Run the post-setup steps first."
+  exit 1
+}
+
+# ── Ensure workspace directory exists on remote ─────────────────────
+REMOTE_ENV="~/opencode-devbox/.env"
+WORKSPACE_PATH=$(ssh_cmd "grep -E '^\s*WORKSPACE_PATH=' $REMOTE_ENV 2>/dev/null | cut -d= -f2- | tr -d '\"'" 2>/dev/null || true)
+if [[ -n "$WORKSPACE_PATH" ]]; then
+  info "Ensuring WORKSPACE_PATH (${WORKSPACE_PATH}) exists on ${SSH_HOST}..."
+  ssh_cmd "mkdir -p ${WORKSPACE_PATH}"
+  ok "Workspace directory ready"
+else
+  # Default from docker-compose.yml is ~/projects or current dir
+  WORKSPACE_PATH=$(echo "$REMOTE_COMPOSE_CONTENT" | grep -oP 'WORKSPACE_PATH:-[^}]+' | sed 's/WORKSPACE_PATH:-//' || true)
+  if [[ -n "$WORKSPACE_PATH" && "$WORKSPACE_PATH" != "." ]]; then
+    info "Ensuring default WORKSPACE_PATH (${WORKSPACE_PATH}) exists on ${SSH_HOST}..."
+    ssh_cmd "mkdir -p ${WORKSPACE_PATH}"
+    ok "Workspace directory ready"
+  fi
+fi
+
+# ── Detect active bind mounts ──────────────────────────────────────
+SYNCED=0
+
+for entry in "${MOUNT_PATTERNS[@]}"; do
+  IFS='|' read -r pattern local_path remote_path <<< "$entry"
+
+  # Check if the mount is uncommented (active) in docker-compose.yml
+  # Match lines that start with optional whitespace and a dash, NOT preceded by #
+  if echo "$REMOTE_COMPOSE_CONTENT" | grep -qE "^\s*-\s+['\"]?${pattern}" 2>/dev/null; then
+    # Mount is active — check if local source exists
+    if [[ ! -d "$local_path" ]]; then
+      warn "Mount active for ${pattern} but ${local_path} does not exist locally — skipping"
+      continue
+    fi
+
+    # Check if directory has content
+    if [[ -z "$(ls -A "$local_path" 2>/dev/null)" ]]; then
+      warn "${local_path} is empty — skipping"
+      continue
+    fi
+
+    info "Syncing ${local_path} → ${SSH_HOST}:${remote_path}"
+
+    # Ensure remote directory exists
+    ssh_cmd "mkdir -p ${remote_path}"
+
+    # Sync with rsync (fall back to scp if rsync unavailable)
+    # Exclude generated/cached content that gets recreated on the remote.
+    # Use -rlptD (archive minus -o -g) so ownership on the remote is set
+    # by the receiving user (devbox). Preserving host UID/GID with -a
+    # tagged files with the pusher's numeric GID, which leaked through
+    # whenever the VM happened to have a matching group (see #group-1001).
+    if command -v rsync &>/dev/null; then
+      rsync -rlptDz --progress \
+        --exclude='node_modules' \
+        --exclude='__pycache__' \
+        --exclude='.venv' \
+        --exclude='*.pyc' \
+        --exclude='cli/cache' \
+        --exclude='sso/cache' \
+        -e "ssh ${SSH_OPTS}" "${local_path}/" "${SSH_HOST}:${remote_path}/"
+    else
+      scp -o "ControlPath=${CTRL_SOCKET}" -r "${local_path}/." "${SSH_HOST}:${remote_path}/"
+    fi
+
+    ok "Synced ${local_path}"
+    SYNCED=$((SYNCED + 1))
+  fi
+done
+
+# ── Summary ─────────────────────────────────────────────────────────
+echo ""
+if [[ $SYNCED -eq 0 ]]; then
+  warn "No active bind mounts detected in remote docker-compose.yml"
+  warn "Uncomment the mounts you need in ${REMOTE_COMPOSE} on the VM, then re-run this script"
+else
+  ok "Synced ${SYNCED} director$([ $SYNCED -eq 1 ] && echo 'y' || echo 'ies') to ${SSH_HOST}"
+fi

docker-compose.shared.yml

@@ -0,0 +1,72 @@
+# opencode-devbox docker-compose for shared machines
+#
+# For machines where multiple users share one OS account (e.g. 'garage').
+# Each user gets isolated config, data, and named volumes by setting
+# SIGNUM in their .env file.
+#
+# Setup per user:
+#   1. mkdir -p ~/<signum>/opencode-devbox && cd ~/<signum>/opencode-devbox
+#   2. cp docker-compose.shared.yml docker-compose.yml
+#   3. cp .env.shared.example .env
+#   4. Edit .env with your signum, provider, keys, etc.
+#   5. mkdir -p ~/<signum>/.config/opencode
+#   6. docker compose up -d
+#
+# Volume isolation: the top-level 'name:' field derives a unique project
+# name per user, which Docker Compose uses as the prefix for all named
+# volumes. Without this, two users whose compose file lives in a directory
+# with the same basename would share volumes — the Docker daemon is
+# system-wide and doesn't scope by OS user.
+#
+# Two modes:
+#   Own-account mode (each user has their own OS login):
+#     Leave SIGNUM unset in .env — it defaults to $USER automatically.
+#   Shared-account mode (everyone logs in as the same OS user):
+#     Set SIGNUM=<unique-id> in .env so each person gets isolated volumes.
+
+name: devbox-${SIGNUM:-${USER}}
+
+services:
+  devbox:
+    image: joakimp/opencode-devbox:latest
+    container_name: devbox-${SIGNUM:-${USER}}
+    stdin_open: true
+    tty: true
+    env_file:
+      - .env
+    environment:
+      - TERM=xterm-256color
+    volumes:
+      # Host workspace — user's project directory
+      - ${WORKSPACE_PATH:-~/src}:/workspace
+
+      # SSH keys — user-specific if available, else shared
+      - ${SSH_KEY_PATH:-~/.ssh}:/home/developer/.ssh:ro
+
+      # Opencode config — per-user (persists settings across restarts)
+      - ${HOME}/${SIGNUM}/.config/opencode:/home/developer/.config/opencode
+
+      # Persist opencode data (auth, memory, session history)
+      - devbox-data:/home/developer/.local/share/opencode
+
+      # Persist bash history across container recreations
+      - devbox-shell-history:/home/developer/.cache/bash
+
+      # Persist zoxide directory history ('z <fragment>' to jump)
+      - devbox-zoxide:/home/developer/.local/share/zoxide
+
+      # Persist neovim plugin/Mason data (avoids re-downloading on every recreate)
+      - devbox-nvim-data:/home/developer/.local/share/nvim
+
+      # Persist uv data (Python installs)
+      - devbox-uv:/home/developer/.local/share/uv
+
+      # Optional: AWS credentials (per-user if available)
+      # - ${HOME}/${SIGNUM}/.aws:/home/developer/.aws
+
+volumes:
+  devbox-data:
+  devbox-shell-history:
+  devbox-zoxide:
+  devbox-nvim-data:
+  devbox-uv:

docker-compose.yml

@@ -3,19 +3,29 @@
 # Usage:
 #   cp .env.example .env    # configure your provider and keys
 #   docker compose up -d
-#   docker compose exec devbox opencode
+#   docker compose exec -u developer devbox opencode
 #
 # Or for interactive one-shot:
 #   docker compose run --rm devbox
 
+# Pin the project name so named volumes survive directory renames.
+# Without this, Docker Compose derives the project name from the
+# directory basename — renaming the dir orphans all existing volumes.
+name: opencode-devbox
+
 services:
   devbox:
-    build:
-      context: .
-      args:
-        INSTALL_PYTHON: "false"
-        INSTALL_GO: "false"
-    image: opencode-devbox:latest
+    image: joakimp/opencode-devbox:latest
+    # For multi-agent orchestration, use the omos variant instead:
+    # image: joakimp/opencode-devbox:latest-omos
+    #
+    # To build from source instead of pulling from Docker Hub, uncomment:
+    # build:
+    #   context: .
+    #   args:
+    #     INSTALL_PYTHON: "false"
+    #     INSTALL_GO: "false"
+    #     INSTALL_OMOS: "false"
     container_name: opencode-devbox
     stdin_open: true
     tty: true
@@ -30,18 +40,68 @@ services:
       # SSH keys (read-only) — for git push/pull
       - ${SSH_KEY_PATH:-~/.ssh}:/home/developer/.ssh:ro
 
-      # Optional: mount your own opencode config (MCP servers, custom models, etc.)
-      # - ./opencode.json:/home/developer/.config/opencode/opencode.json:ro
+      # Optional: mount opencode config directory (persists config changes across restarts)
+      # Includes opencode.json, oh-my-opencode-slim.json, skills, etc.
+      # When mounted, OPENCODE_PROVIDER auto-config is skipped if opencode.json exists.
+      # - ~/.config/opencode:/home/developer/.config/opencode
 
-      # Optional: mount opencode skills from host
-      # - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
+      # Optional: mount opencode agent skills from host
       # - ~/.agents/skills:/home/developer/.agents/skills:ro
 
+      # Optional: mount neovim config from host (plugins auto-install on first start)
+      # - ~/.config/nvim:/home/developer/.config/nvim:ro
+
       # Optional: persist opencode data (auth, memory, etc.)
       - devbox-data:/home/developer/.local/share/opencode
 
-      # Optional: AWS credentials for Bedrock
-      # - ~/.aws:/home/developer/.aws:ro
+      # Optional: persist opencode TUI settings (theme, toggles, etc.)
+      - devbox-state:/home/developer/.local/state/opencode
+
+      # Persist bash history across container recreations.
+      # Without this, ~/.bash_history is lost on 'docker compose up --force-recreate'.
+      - devbox-shell-history:/home/developer/.cache/bash
+
+      # Persist zoxide directory history ('z <fragment>' to jump).
+      - devbox-zoxide:/home/developer/.local/share/zoxide
+
+      # Optional: override baked shell defaults with your host's rc files.
+      # The image ships sensible defaults (history tuning, prefix-search on
+      # Up/Down arrows, fzf/zoxide integration). Uncomment to use your own:
+      #
+      # NOTE: Single-file bind-mounts break when editors use atomic save
+      # (vim, VS Code, sed -i write a temp file then rename() over the
+      # original, creating a new inode the container never sees). This is a
+      # kernel limitation, not Docker-specific. If host edits stop appearing
+      # in the container, mount the parent directory instead — see the
+      # "Shell defaults" section in README.md.
+      # - ~/.bash_aliases:/home/developer/.bash_aliases:ro
+      # - ~/.inputrc:/home/developer/.inputrc:ro
+
+      # Optional: persist uv data (Python installs, tool installs)
+      # Without this, 'uv python install' must be re-run after container removal.
+      - devbox-uv:/home/developer/.local/share/uv
+
+      # Optional: persist Rust toolchains and cargo data
+      # Without this, 'rustup-init' must be re-run after container removal.
+      # - devbox-rustup:/home/developer/.rustup
+      # - devbox-cargo:/home/developer/.cargo
+
+      # Optional: persist VS Code server and extensions across container recreations
+      # - devbox-vscode:/home/developer/.vscode-server
+
+      # Persist neovim plugin/Mason data (avoids re-downloading on every recreate)
+      - devbox-nvim-data:/home/developer/.local/share/nvim
+
+      # Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
+      # - ~/.aws:/home/developer/.aws
 
 volumes:
   devbox-data:
+  devbox-state:
+  devbox-shell-history:
+  devbox-zoxide:
+  devbox-nvim-data:
+  devbox-uv:
+  # devbox-rustup:
+  # devbox-cargo:
+  # devbox-vscode:

entrypoint-user.sh

@@ -1,6 +1,20 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# ── Shell defaults: copy baked files from /etc/skel-devbox/ if absent
+# Respects host bind-mounts and user customizations — existing files
+# are never overwritten. To restore defaults: rm ~/.bash_aliases (or
+# .inputrc) and recreate the container, or cp from /etc/skel-devbox/
+# directly.
+SKEL_DIR="/etc/skel-devbox"
+if [ -d "$SKEL_DIR" ]; then
+  for f in .bash_aliases .inputrc; do
+    if [ -f "$SKEL_DIR/$f" ] && [ ! -e "$HOME/$f" ]; then
+      cp "$SKEL_DIR/$f" "$HOME/$f"
+    fi
+  done
+fi
+
 # ── Git config defaults ──────────────────────────────────────────────
 if [ -n "${GIT_USER_NAME:-}" ] && ! git config --global user.name &>/dev/null; then
   git config --global user.name "$GIT_USER_NAME"
@@ -22,7 +36,7 @@ if [ ! -f "$CONFIG_FILE" ] && [ -n "${OPENCODE_PROVIDER:-}" ]; then
       cat > "$CONFIG_FILE" <<EOF
 {
   "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-5}",
+  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-6}",
   "share": "disabled",
   "autoupdate": false
 }
@@ -32,7 +46,7 @@ EOF
       cat > "$CONFIG_FILE" <<EOF
 {
   "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-openai/gpt-4o}",
+  "model": "${OPENCODE_MODEL:-openai/gpt-5.4}",
   "share": "disabled",
   "autoupdate": false
 }
@@ -42,13 +56,14 @@ EOF
       cat > "$CONFIG_FILE" <<EOF
 {
   "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-amazon-bedrock/anthropic.claude-sonnet-4-5-v1}",
+  "model": "${OPENCODE_MODEL:-amazon-bedrock/global.anthropic.claude-sonnet-4-5-20250929-v1:0}",
   "share": "disabled",
   "autoupdate": false,
   "provider": {
     "amazon-bedrock": {
       "options": {
-        "region": "${AWS_REGION:-us-east-1}"
+        "region": "${AWS_REGION:-us-east-1}",
+        "profile": "${AWS_PROFILE:-default}"
       }
     }
   }
@@ -59,7 +74,7 @@ EOF
       cat > "$CONFIG_FILE" <<EOF
 {
   "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-5}",
+  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-6}",
   "share": "disabled",
   "autoupdate": false
 }
@@ -68,5 +83,54 @@ EOF
   esac
 fi
 
+# ── oh-my-opencode-slim setup (multi-agent orchestration) ────────────
+# Activated by ENABLE_OMOS=true. Requires the image to be built with
+# INSTALL_OMOS=true (which installs bun + the oh-my-opencode-slim package).
+OMOS_CONFIG="$CONFIG_DIR/oh-my-opencode-slim.json"
+
+if [ "${ENABLE_OMOS:-false}" = "true" ]; then
+  if ! command -v bunx &>/dev/null; then
+    echo "WARNING: ENABLE_OMOS=true but bun is not installed."
+    echo "Rebuild with: docker compose build --build-arg INSTALL_OMOS=true"
+  elif [ ! -f "$OMOS_CONFIG" ]; then
+    echo "Setting up oh-my-opencode-slim agents..."
+
+    # Determine installer flags
+    OMOS_TMUX_FLAG="no"
+    if [ "${OMOS_TMUX:-false}" = "true" ]; then
+      OMOS_TMUX_FLAG="yes"
+    fi
+
+    OMOS_SKILLS_FLAG="yes"
+    if [ "${OMOS_SKILLS:-true}" = "false" ]; then
+      OMOS_SKILLS_FLAG="no"
+    fi
+
+    bunx oh-my-opencode-slim@latest install \
+      --no-tui \
+      --tmux="${OMOS_TMUX_FLAG}" \
+      --skills="${OMOS_SKILLS_FLAG}"
+
+    echo "oh-my-opencode-slim configured successfully."
+  else
+    echo "oh-my-opencode-slim config found at $OMOS_CONFIG (use OMOS_RESET=true to overwrite)."
+
+    # Allow reset via env var (creates backup automatically)
+    if [ "${OMOS_RESET:-false}" = "true" ]; then
+      echo "OMOS_RESET=true — regenerating oh-my-opencode-slim config..."
+      OMOS_TMUX_FLAG="no"
+      [ "${OMOS_TMUX:-false}" = "true" ] && OMOS_TMUX_FLAG="yes"
+      OMOS_SKILLS_FLAG="yes"
+      [ "${OMOS_SKILLS:-true}" = "false" ] && OMOS_SKILLS_FLAG="no"
+
+      bunx oh-my-opencode-slim@latest install \
+        --no-tui \
+        --tmux="${OMOS_TMUX_FLAG}" \
+        --skills="${OMOS_SKILLS_FLAG}" \
+        --reset
+    fi
+  fi
+fi
+
 # ── Execute command ──────────────────────────────────────────────────
 exec "$@"

entrypoint.sh

@@ -6,18 +6,22 @@ CURRENT_UID=$(id -u "$USER_NAME")
 CURRENT_GID=$(id -g "$USER_NAME")
 
 # ── UID/GID adjustment ───────────────────────────────────────────────
-# Priority: env vars > auto-detect from /workspace > default (1000)
+# Priority per dimension: env var > auto-detect from /workspace > no-op
+# UID and GID are detected independently so a GID-only mismatch (e.g. host
+# user has UID 1000 but primary group at GID 1001) is still corrected.
 TARGET_UID="${USER_UID:-}"
 TARGET_GID="${USER_GID:-}"
 
-# Auto-detect from /workspace owner if env vars not set
-if [ -z "$TARGET_UID" ] && [ -d /workspace ]; then
-  WORKSPACE_UID=$(stat -c '%u' /workspace 2>/dev/null || stat -f '%u' /workspace 2>/dev/null)
-  WORKSPACE_GID=$(stat -c '%g' /workspace 2>/dev/null || stat -f '%g' /workspace 2>/dev/null)
-  # Only adjust if workspace is owned by a non-root user
-  if [ "$WORKSPACE_UID" != "0" ] && [ "$WORKSPACE_UID" != "$CURRENT_UID" ]; then
+if [ -d /workspace ]; then
+  WORKSPACE_UID=$(stat -c '%u' /workspace 2>/dev/null || stat -f '%u' /workspace 2>/dev/null || echo "")
+  WORKSPACE_GID=$(stat -c '%g' /workspace 2>/dev/null || stat -f '%g' /workspace 2>/dev/null || echo "")
+  # Adopt workspace UID if env var not set and workspace is non-root-owned
+  if [ -z "$TARGET_UID" ] && [ -n "$WORKSPACE_UID" ] && [ "$WORKSPACE_UID" != "0" ] && [ "$WORKSPACE_UID" != "$CURRENT_UID" ]; then
     TARGET_UID="$WORKSPACE_UID"
-    TARGET_GID="${TARGET_GID:-$WORKSPACE_GID}"
+  fi
+  # Adopt workspace GID if env var not set and workspace group differs
+  if [ -z "$TARGET_GID" ] && [ -n "$WORKSPACE_GID" ] && [ "$WORKSPACE_GID" != "0" ] && [ "$WORKSPACE_GID" != "$CURRENT_GID" ]; then
+    TARGET_GID="$WORKSPACE_GID"
   fi
 fi
 
@@ -25,12 +29,13 @@ fi
 if [ -n "$TARGET_GID" ] && [ "$TARGET_GID" != "$CURRENT_GID" ]; then
   groupmod -g "$TARGET_GID" "$USER_NAME" 2>/dev/null || true
   find /home/"$USER_NAME" -not -path "/home/$USER_NAME/.ssh/*" -group "$CURRENT_GID" -exec chgrp "$TARGET_GID" {} + 2>/dev/null || true
+  echo "Adjusted developer GID to $TARGET_GID"
 fi
 
 if [ -n "$TARGET_UID" ] && [ "$TARGET_UID" != "$CURRENT_UID" ]; then
   usermod -u "$TARGET_UID" "$USER_NAME" 2>/dev/null || true
   find /home/"$USER_NAME" -not -path "/home/$USER_NAME/.ssh/*" -user "$CURRENT_UID" -exec chown "$TARGET_UID" {} + 2>/dev/null || true
-  echo "Adjusted developer UID:GID to $TARGET_UID:${TARGET_GID:-$CURRENT_GID}"
+  echo "Adjusted developer UID to $TARGET_UID"
 fi
 
 # ── SSH key permissions ──────────────────────────────────────────────
@@ -46,5 +51,45 @@ if [ -d "/home/$USER_NAME/.ssh" ] && [ "$(ls -A "/home/$USER_NAME/.ssh" 2>/dev/n
   fi
 fi
 
+# ── Fix ownership of named volume mount points ──────────────────────
+# Named volumes are created as root on first use. Fix ownership so the
+# developer user can write to them.
+FINAL_UID="${TARGET_UID:-$CURRENT_UID}"
+FINAL_GID="${TARGET_GID:-$CURRENT_GID}"
+
+# First, fix parent dirs that Docker auto-creates as root:root when it
+# materializes nested mount points (e.g. mounting a volume at
+# .local/state/opencode creates .local/state as root). Non-recursive —
+# we only need the dir node itself; children are handled below or were
+# created by the user.
+for parent in \
+  /home/"$USER_NAME"/.local \
+  /home/"$USER_NAME"/.local/share \
+  /home/"$USER_NAME"/.local/state \
+  /home/"$USER_NAME"/.cache \
+  /home/"$USER_NAME"/.config; do
+  if [ -d "$parent" ] && [ "$(stat -c '%u' "$parent" 2>/dev/null)" != "$FINAL_UID" ]; then
+    chown "$FINAL_UID":"$FINAL_GID" "$parent" 2>/dev/null || true
+  fi
+done
+
+for dir in \
+  /home/"$USER_NAME"/.local/share/opencode \
+  /home/"$USER_NAME"/.local/state/opencode \
+  /home/"$USER_NAME"/.local/share/uv \
+  /home/"$USER_NAME"/.local/share/zoxide \
+  /home/"$USER_NAME"/.local/share/nvim \
+  /home/"$USER_NAME"/.cache/bash \
+  /home/"$USER_NAME"/.rustup \
+  /home/"$USER_NAME"/.cargo \
+  /home/"$USER_NAME"/.vscode-server \
+  /home/"$USER_NAME"/.config/opencode \
+  /home/"$USER_NAME"/.config/nvim \
+  /home/"$USER_NAME"/.agents/skills; do
+  if [ -d "$dir" ] && [ "$(stat -c '%u' "$dir" 2>/dev/null)" != "$FINAL_UID" ]; then
+    chown -R "$FINAL_UID":"$FINAL_GID" "$dir" 2>/dev/null || true
+  fi
+done
+
 # ── Drop to developer user for remaining setup ──────────────────────
 exec gosu "$USER_NAME" /usr/local/bin/entrypoint-user.sh "$@"

rootfs/home/developer/.bash_aliases

@@ -0,0 +1,94 @@
+# opencode-devbox bash aliases and customizations
+# Sourced by the Debian-default ~/.bashrc on shell startup.
+# To override, bind-mount your host's ~/.bash_aliases over this file
+# via docker-compose.yml.
+
+# ── Host-shared shell customizations (devbox-shell bridge) ───────────
+# If the host bind-mounts a directory at ~/.config/devbox-shell/ (the
+# recommended pattern for sharing aliases/PATH/utilities between host
+# and container), source the bash_aliases file from it. This survives
+# --force-recreate because it's baked into the image's skel, not the
+# container's writable layer. Hosts that don't use this pattern are
+# unaffected — the test silently skips if the file doesn't exist.
+[ -r "$HOME/.config/devbox-shell/bash_aliases" ] && . "$HOME/.config/devbox-shell/bash_aliases"
+
+# ── History persistence and quality ──────────────────────────────────
+# The named volume devbox-shell-history is mounted at ~/.cache/bash
+# so history survives container recreation.
+export HISTFILE="${HOME}/.cache/bash/history"
+mkdir -p "$(dirname "$HISTFILE")" 2>/dev/null || true
+
+# Large, time-stamped, deduplicated history. Append rather than overwrite.
+export HISTSIZE=100000
+export HISTFILESIZE=200000
+export HISTCONTROL=ignoreboth:erasedups
+export HISTTIMEFORMAT='%F %T  '
+shopt -s histappend 2>/dev/null
+shopt -s cmdhist 2>/dev/null
+# Note: PROMPT_COMMAND="history -a" is installed LATER in this file,
+# after zoxide's init runs. Installing it here would create a
+# "history -a;;__zoxide_hook" chain because zoxide's init uses ';'
+# as its separator and prepends itself; two adjacent ';' breaks the
+# parser. See https://github.com/ajeetdsouza/zoxide/issues/722.
+
+# ── Common aliases ───────────────────────────────────────────────────
+# Prefer eza (modern ls) when available
+if command -v eza >/dev/null 2>&1; then
+  alias ls='eza --group-directories-first'
+  alias ll='eza -lh --group-directories-first --git'
+  alias la='eza -lha --group-directories-first --git'
+  alias tree='eza --tree'
+else
+  alias ll='ls -lh'
+  alias la='ls -lha'
+fi
+
+# Prefer bat (syntax-highlighted cat) when available
+if command -v bat >/dev/null 2>&1; then
+  alias cat='bat --style=plain --paging=never'
+  alias less='bat --paging=always'
+fi
+
+# Git shortcuts
+alias gs='git status'
+alias gd='git diff'
+alias gl='git log --oneline --graph --decorate -20'
+
+# Safety: confirm before destructive ops
+alias rm='rm -i'
+alias mv='mv -i'
+alias cp='cp -i'
+
+# ── Shell integrations ───────────────────────────────────────────────
+# zoxide — smarter cd. Use 'z <fragment>' to jump to previously-visited dirs.
+if command -v zoxide >/dev/null 2>&1; then
+  eval "$(zoxide init bash)"
+fi
+
+# fzf — fuzzy finder key bindings (Ctrl-R for history, Ctrl-T for files).
+# We install fzf from GitHub releases (not apt), so sourcing from the
+# apt-path /usr/share/doc/fzf/examples/* would find nothing. Use the
+# binary's own --bash flag (available since fzf 0.48) for setup.
+if command -v fzf >/dev/null 2>&1; then
+  eval "$(fzf --bash)" 2>/dev/null || true
+fi
+
+# ── PROMPT_COMMAND: flush history every prompt ───────────────────────
+# Installed AFTER zoxide init so zoxide's hook is already in place;
+# we append with a newline separator to avoid the ';;' parse error
+# described at the top of this file. Guarded so repeated sourcing
+# (e.g. `exec bash`) doesn't stack duplicates.
+if [ -z "${DEVBOX_HIST_SET:-}" ]; then
+  PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND$'\n'}history -a"
+  export DEVBOX_HIST_SET=1
+fi
+
+# ── Prompt: show [opencode-devbox] tag so it's obvious you're in the container
+# Preserves the default Debian PS1 logic but prefixes with a container marker.
+# We check for the literal '[devbox]' substring in PS1 rather than relying on
+# an exported guard variable — otherwise `exec bash` inherits the guard but
+# gets a fresh (prefix-less) PS1 from .bashrc, and the prefix would never be
+# re-added in the new shell.
+if [ -n "${PS1:-}" ] && [[ "$PS1" != *"[devbox]"* ]]; then
+  PS1='\[\e[38;5;39m\][devbox]\[\e[0m\] '"${PS1}"
+fi

rootfs/home/developer/.inputrc

@@ -0,0 +1,27 @@
+# opencode-devbox readline defaults
+# To override, bind-mount your host's ~/.inputrc over this file
+# via docker-compose.yml.
+
+# Inherit system-wide defaults (colour, 8-bit input, …) if present
+$include /etc/inputrc
+
+# ── History search on Up/Down ────────────────────────────────────────
+# Type a prefix, press Up, and walk through previous commands starting
+# with that prefix. Ctrl-Up / Ctrl-Down keep the unconditional stepper.
+"\e[A": history-search-backward
+"\e[B": history-search-forward
+"\e[1;5A": previous-history
+"\e[1;5B": next-history
+
+# ── Completion quality ───────────────────────────────────────────────
+set show-all-if-ambiguous on      # single Tab shows matches on ambiguity
+set completion-ignore-case on     # case-insensitive file/dir completion
+set colored-stats on              # colour ls-style completion list entries
+set colored-completion-prefix on  # highlight the matched prefix
+set visible-stats on              # append /*@ type indicators in completion
+set mark-symlinked-directories on # add trailing / to symlinks to dirs
+set skip-completed-text on        # don't re-insert already-typed text
+
+# Treat hyphens and underscores as equivalent when completing (e.g.
+# typing `foo-` matches both `foo-bar` and `foo_bar`).
+set completion-map-case on