Add devbox-shell bridge line to baked .bash_aliases

If the host bind-mounts ~/.config/devbox-shell/ into the container
(the directory-mount pattern that avoids single-file inode breakage),
the container needs a bridge line in .bashrc or .bash_aliases to
source the mounted file. Previously this bridge had to be re-added
manually after every --force-recreate because it lived in the
container's writable layer.

Baking it into the skel .bash_aliases makes it automatic: every
fresh container sources ~/.config/devbox-shell/bash_aliases if it
exists, with zero manual steps. Hosts that don't use the devbox-shell
pattern are unaffected — the [ -r ... ] test silently skips.

.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=
@@ -31,6 +31,11 @@ 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

.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

@@ -105,21 +105,21 @@ jobs:
 
       - 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)
+            -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. Available in base and omos (multi-agent) variants." \
+            --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 /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 @-)
           echo "Docker Hub API returned: $HTTP_CODE"

.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)`

DOCKER_HUB.md

@@ -114,12 +114,54 @@ 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 |
 
-## Initial Setup
+### Locale and Editor
 
-### 1. Create a project directory
+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
+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
@@ -145,7 +187,7 @@ GIT_USER_EMAIL=you@example.com
 **AWS Bedrock (SSO):**
 ```bash
 OPENCODE_PROVIDER=amazon-bedrock
-OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
+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
@@ -184,18 +226,30 @@ Understanding what survives container restarts and what doesn't:
 | `/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` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, oh-my-opencode-slim.json, skills |
+| `/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 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 with `--rm` unless you add a named volume.
+- **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 over opencode settings (MCP servers, custom models, oh-my-opencode-slim agents, etc.), mount the entire config directory from the host:
+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 \
@@ -206,6 +260,8 @@ docker run -it --rm \
 
 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:
@@ -217,6 +273,114 @@ docker run -it --rm \
   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 directory with a `docker-compose.yml` and a `.env` file:
@@ -229,7 +393,7 @@ mkdir opencode-devbox && cd opencode-devbox
 
 ```bash
 OPENCODE_PROVIDER=amazon-bedrock
-OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
+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
@@ -244,6 +408,7 @@ services:
     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:
@@ -254,6 +419,13 @@ services:
       - ~/projects:/workspace
       - ~/.ssh:/home/developer/.ssh:ro
       - devbox-data:/home/developer/.local/share/opencode
+      - 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)
@@ -265,6 +437,11 @@ services:
 
 volumes:
   devbox-data:
+  devbox-state:
+  devbox-uv:
+  # devbox-rustup:
+  # devbox-cargo:
+  # devbox-vscode:
 ```
 
 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.
@@ -290,15 +467,28 @@ 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
 
 ### Base image (`latest`)
 
-- **Debian bookworm-slim** — glibc, full terminal/PTY support
+- **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, bat, eza, zoxide, jq, make, curl, wget, neovim 0.12, tmux, htop, 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`)
@@ -359,6 +549,10 @@ 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)

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.22
 
 LABEL maintainer="joakimp"
 LABEL description="Portable opencode developer container"
@@ -32,10 +32,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     make \
     patch \
     diffutils \
+    git-crypt \
+    age \
+    file \
     sudo \
     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/*
 
@@ -71,7 +79,7 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;
     nvim --version | head -1
 
 # bat — syntax-highlighted cat replacement
-ARG BAT_VERSION=0.25.0
+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 && \
@@ -90,12 +98,31 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
     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
 
-# Set locale
-RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
+# 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
@@ -130,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 && \
@@ -141,10 +168,22 @@ RUN if [ "${INSTALL_GO}" = "true" ]; then \
 # ── 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 \
-      curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash && \
+      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
@@ -163,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,19 +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:
@@ -103,6 +117,10 @@ docker compose exec -u developer devbox aws --version
 | `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` |
@@ -110,14 +128,16 @@ docker compose exec -u developer devbox aws --version
 
 ### Custom opencode config
 
-For full control over opencode settings (MCP servers, custom models, oh-my-opencode-slim agents, etc.), mount the entire config directory from the host:
+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:
   - ~/.config/opencode:/home/developer/.config/opencode
 ```
 
-This persists all configuration changes across container restarts, including `opencode.json`, `oh-my-opencode-slim.json`, and skills. When an existing `opencode.json` is found, the `OPENCODE_PROVIDER` auto-config is skipped.
+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
 
@@ -137,6 +157,161 @@ 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:
@@ -269,6 +444,51 @@ The `--use-device-code` flag outputs a URL and short code instead of trying to o
 
 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
 
 A [gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook prevents accidentally committing API keys, passwords, or other secrets.
@@ -306,12 +526,12 @@ Host Machine
 ├── ~/.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)
-├── neovim 0.12, tmux, htop, bat, eza, zoxide, make
-├── git, ssh, ripgrep, fd, fzf, jq, curl, tree
+├── 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)
 ├── Bun (optional — included with oh-my-opencode-slim)
 ├── entrypoint.sh (UID adjustment, git config, provider setup)
@@ -326,7 +546,15 @@ Container (Debian bookworm)
 | `/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` | Host bind mount (if configured) | ✅ Yes | opencode.json, oh-my-opencode-slim.json, skills |
+| `/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 persist config changes and use custom settings, mount the config directory from the host (see Custom opencode config above).
 

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,282 @@
+# 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`.
+
+### 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

@@ -8,15 +8,24 @@
 # 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"
-        INSTALL_OMOS: "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
@@ -45,8 +54,54 @@ services:
       # Optional: persist opencode data (auth, memory, etc.)
       - devbox-data:/home/developer/.local/share/opencode
 
+      # 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
 }

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