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.shared.example

@@ -1,7 +1,13 @@
 # ── Shared machine setup ─────────────────────────────────────────────
-# Your corporate signum / username (REQUIRED)
+# SIGNUM isolates your container name and named volumes from other users.
-# This isolates your container, config, and data from other users.
+#
-SIGNUM=your-signum-here
+# 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

AGENTS.md

@@ -15,7 +15,16 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d
 
 ## Versioning scheme
 
-Tags follow `v{opencode_version}{letter}` — e.g. `v1.4.3k`. The number matches the opencode npm version. The letter suffix increments for container-level changes (tooling, docs, CVE fixes) on the same opencode version. CI produces four Docker Hub tags per release: `vX.Y.Zn`, `latest`, `vX.Y.Zn-omos`, `latest-omos`.
+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
 

DOCKER_HUB.md

@@ -227,6 +227,9 @@ Understanding what survives container restarts and what doesn't:
 | `/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/.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 |
@@ -239,6 +242,7 @@ Understanding what survives container restarts and what doesn't:
 - **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start if no existing config is found. To persist config changes, mount the config directory from the host (see Custom opencode Config below).
 - **opencode data** (session history, memory) is lost on container recreation unless you add a named volume.
 - **TUI settings** (theme, toggles) are lost on container recreation unless you add the `devbox-state` named volume.
+- **Bash history** persists via the `devbox-shell-history` volume mounted at `~/.cache/bash`. `HISTFILE` is pre-configured; no setup required.
 - **Python installs** via `uv python install` are lost on container recreation unless you add the `devbox-uv` named volume.
 - **Rust toolchains** via `rustup-init` are lost on container recreation unless you add the `devbox-rustup` and `devbox-cargo` named volumes.
 - **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
@@ -463,6 +467,19 @@ 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`)
@@ -532,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

@@ -5,7 +5,7 @@ ARG DEBIAN_VERSION=trixie-slim
 FROM debian:${DEBIAN_VERSION} AS base
 
 ARG TARGETARCH
-ARG OPENCODE_VERSION=1.14.19
+ARG OPENCODE_VERSION=1.14.22
 
 LABEL maintainer="joakimp"
 LABEL description="Portable opencode developer container"
@@ -42,6 +42,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     gcc \
     g++ \
     rsync \
+    python3-pip \
+    python3-venv \
     && ln -s /usr/bin/fdfind /usr/local/bin/fd \
     && rm -rf /var/lib/apt/lists/*
 
@@ -200,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

@@ -273,11 +273,17 @@ volumes:
   - devbox-vscode:/home/developer/.vscode-server
 ```
 
-### Shared machine setup (multiple users, single OS account)
+### Multi-user setup
 
-For machines where multiple users share one OS account (e.g. a common `garage` user), a separate compose file isolates each user's config and data using a `SIGNUM` variable.
+The shared-machine compose file (`docker-compose.shared.yml`) supports two modes:
 
-Each user creates their own directory and setup:
+**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
@@ -291,17 +297,17 @@ cp /path/to/opencode-devbox/.env.shared.example .env
 # Create per-user config directory
 mkdir -p ~/<signum>/.config/opencode
 
-# Edit .env with your signum, provider, keys, etc.
+# 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-<signum> opencode
+docker compose exec -u developer devbox opencode
 ```
 
 Each user's container, config, and named volumes are fully isolated:
-- Container name: `devbox-<signum>` (no collisions)
+- Container name: `devbox-<signum>` (or `devbox-$USER` in own-account mode)
-- Named volumes: prefixed with the project directory name (automatic per-user isolation)
+- 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.
@@ -438,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.
@@ -496,6 +547,9 @@ Container (Debian trixie)
 | `/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/.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 |

deploy/README.md

@@ -197,3 +197,86 @@ After editing `docker-compose.yml` on the VM to uncomment the bind mounts you ne
 ```
 
 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.

docker-compose.shared.yml

@@ -12,14 +12,24 @@
 #   5. mkdir -p ~/<signum>/.config/opencode
 #   6. docker compose up -d
 #
-# Named volumes are automatically isolated per user because Docker Compose
+# Volume isolation: the top-level 'name:' field derives a unique project
-# prefixes them with the project directory name (e.g. opencode-devbox_devbox-data).
+# name per user, which Docker Compose uses as the prefix for all named
-# Since each user runs from ~/<signum>/opencode-devbox/, volumes don't collide.
+# 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:?Set SIGNUM in .env}
+    container_name: devbox-${SIGNUM:-${USER}}
     stdin_open: true
     tty: true
     env_file:
@@ -39,6 +49,15 @@ services:
       # 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
 
@@ -47,4 +66,7 @@ services:
 
 volumes:
   devbox-data:
+  devbox-shell-history:
+  devbox-zoxide:
+  devbox-nvim-data:
   devbox-uv:

docker-compose.yml

@@ -8,6 +8,11 @@
 # 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:
     image: joakimp/opencode-devbox:latest
@@ -52,6 +57,26 @@ services:
       # 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
@@ -64,12 +89,18 @@ services:
       # 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:

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"

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 [ -d /workspace ]; then
-if [ -z "$TARGET_UID" ] && [ -d /workspace ]; then
+  WORKSPACE_UID=$(stat -c '%u' /workspace 2>/dev/null || stat -f '%u' /workspace 2>/dev/null || echo "")
-  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 || echo "")
-  WORKSPACE_GID=$(stat -c '%g' /workspace 2>/dev/null || stat -f '%g' /workspace 2>/dev/null)
+  # Adopt workspace UID if env var not set and workspace is non-root-owned
-  # Only adjust if workspace is owned by a non-root user
+  if [ -z "$TARGET_UID" ] && [ -n "$WORKSPACE_UID" ] && [ "$WORKSPACE_UID" != "0" ] && [ "$WORKSPACE_UID" != "$CURRENT_UID" ]; then
-  if [ "$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 ──────────────────────────────────────────────
@@ -61,6 +66,7 @@ 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
@@ -71,6 +77,9 @@ 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 \

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