Update devcontainer configuration to use bind mounts for home directory and add onCreateCommand for seeding

Author: chapterjason

.devcontainer/devcontainer.json

@@ -11,8 +11,9 @@
   "remoteUser": "${localEnv:DEVCONTAINER_USERNAME:dev}",
   "containerUser": "${localEnv:DEVCONTAINER_USERNAME:dev}",
   "mounts": [
-    "source=devhome-${localEnv:OWNER_USERNAME:shared},target=/home/${localEnv:DEVCONTAINER_USERNAME:dev},type=volume"
+    "source=/mnt/devhome,target=/home/${localEnv:DEVCONTAINER_USERNAME:dev},type=bind"
   ],
+  "onCreateCommand": "test -z \"$(ls -A $HOME 2>/dev/null)\" && cp -rT /etc/skel $HOME || true",
   "features": {
     "ghcr.io/sourecode/devcontainer-features/nvm:2": {},
     "ghcr.io/sourecode/devcontainer-features/claude-code:2": {},

docs/migration-guide.md

@@ -48,8 +48,9 @@ An existing devcontainer that:
   "remoteUser": "${localEnv:DEVCONTAINER_USERNAME:dev}",
   "containerUser": "${localEnv:DEVCONTAINER_USERNAME:dev}",
   "mounts": [
-    "source=devhome-${localEnv:OWNER_USERNAME:shared},target=/home/${localEnv:DEVCONTAINER_USERNAME:dev},type=volume"
+    "source=/mnt/devhome,target=/home/${localEnv:DEVCONTAINER_USERNAME:dev},type=bind"
   ],
+  "onCreateCommand": "test -z \"$(ls -A $HOME 2>/dev/null)\" && cp -rT /etc/skel $HOME || true",
   "features": {
     // pick from the feature reference below
   },
@@ -62,10 +63,15 @@ An existing devcontainer that:
 Rules:
 
 - `name` — keep the project's existing name.
-- Volume name is **always** `devhome-${localEnv:OWNER_USERNAME:shared}`. Do
-  **not** add the project name to the volume — the point is that every
-  project shares one home per user. Fallback `:shared` kicks in when running
-  the devcontainer locally outside Coder.
+- Mount **source** is **always** `/mnt/devhome`, mount **type** is
+  **always** `bind`. That path is the per-owner home volume mounted into
+  every outer Coder workspace (see `main.tf`'s `docker_volume "devhome"`).
+  Do **not** introduce per-project volume names — the whole point is that
+  every project shares one home per owner.
+- `onCreateCommand` is required. Bind mounts don't auto-seed from the
+  image, so this line copies `/etc/skel` into `$HOME` on the first-ever
+  create and no-ops on every subsequent create. See
+  [`persistence.md`](persistence.md#seeding-on-first-create).
 - `remoteUser` and `containerUser` both use `${localEnv:DEVCONTAINER_USERNAME:dev}`.
 - Do **not** set `CLAUDE_CONFIG_DIR` or `SCCACHE_DIR` in `containerEnv` —
   their defaults (`~/.claude`, `~/.cache/sccache`) already land inside the
@@ -178,19 +184,24 @@ Typical `features` block for a C++ project:
 
 ## Persistent home caveats
 
-One volume per Coder user, shared across every devcontainer they open. This
-is intentional — same bash history, same `~/.gitconfig`, same `~/.claude`
+One volume per Coder *owner*, bind-mounted through every outer workspace
+they open. Shared across every devcontainer they open, in every workspace
+they open. Same bash history, same `~/.gitconfig`, same `~/.claude`,
 everywhere. Side effects to understand:
 
-- First-time volume creation seeds from the image's `/home/<user>` (Docker
-  copies dir contents when an empty named volume is mounted over a
-  non-empty target). Subsequent rebuilds use the volume; changes to the
-  image's home dir will **not** propagate.
+- Bind mounts don't auto-seed. The `onCreateCommand` in the template
+  handles it: empty `$HOME` → copy `/etc/skel`, populated `$HOME` → no-op.
 - Put long-lived shell config in `/etc/bash.bashrc` (image-side) so it
-  stays authoritative.
+  stays authoritative. `~/.bashrc` lives on the volume and is only
+  populated once on the first-ever create; rebuilding the image later
+  does **not** update it.
 - Tools that store env-specific state in `$HOME` (some pyenv/nvm layouts,
   `.cache/` bloat) can collide across projects. Usually fine for dotfiles
   and coarse caches; tune per-project if something misbehaves.
+- Running two workspaces simultaneously shares the same home (same
+  situation as running two terminals on your laptop). Tools that tolerate
+  concurrent writers cope fine; tools that don't behave as they would
+  locally.
 
 ## Checklist for the migrating agent
 

docs/persistence.md

@@ -1,10 +1,11 @@
 # Persisting state across devcontainer rebuilds
 
-Our convention: mount a single named volume at the user's home directory,
-scoped per-Coder-user, shared across every devcontainer that user opens.
-Everything that lives under `$HOME` persists automatically — bash history,
-git config, SSH keys, tool caches, Claude Code state, sccache cache, pipx
-installs, anything.
+Our convention: a single per-owner home volume, bind-mounted through the
+outer Coder workspace into every devcontainer the owner opens. Everything
+under `$HOME` persists automatically — bash history, git config, SSH keys,
+tool caches, Claude Code state, sccache cache, pipx installs, anything —
+and it persists *across workspaces*, not just across rebuilds of one
+workspace.
 
 ## The mount
 
@@ -13,20 +14,60 @@ In every `.devcontainer/devcontainer.json`:
 ```jsonc
 {
   "mounts": [
-    "source=devhome-${localEnv:OWNER_USERNAME:shared},target=/home/${localEnv:DEVCONTAINER_USERNAME:dev},type=volume"
-  ]
+    "source=/mnt/devhome,target=/home/${localEnv:DEVCONTAINER_USERNAME:dev},type=bind"
+  ],
+  "onCreateCommand": "test -z \"$(ls -A $HOME 2>/dev/null)\" && cp -rT /etc/skel $HOME || true"
 }
 ```
 
-- `OWNER_USERNAME` is injected by the Coder template (`coder_agent.main.env`)
-  and resolves to the Coder workspace owner's username.
-- `DEVCONTAINER_USERNAME` is the in-container user (also from
+- `/mnt/devhome` is a stable path inside the outer Coder workspace where
+  the per-owner home volume is mounted (see Topology below).
+- `DEVCONTAINER_USERNAME` is the in-container user (from
   `coder_agent.main.env`; default `dev`).
-- Running outside Coder, both fall back to sensible defaults —
-  `devhome-shared` mounted at `/home/dev`.
+- `onCreateCommand` seeds the home from `/etc/skel` on first-ever attach.
+  Bind mounts don't auto-seed from the image the way named volumes do, so
+  the command copies skeleton dotfiles on the first workspace per owner
+  and no-ops on every subsequent create.
+- Running outside Coder, change the mount `source` to a local path or a
+  named volume — the rest of the devcontainer stays the same.
 
-One volume per Coder user. Open three different project devcontainers and
-they all see the same home.
+One volume per Coder user. Open three different project devcontainers,
+open them from three different workspaces — they all see the same home.
+
+## Topology
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ host dockerd                                                      │
+│                                                                   │
+│   docker volume: coder-<owner>-devhome   ◄──── one per owner      │
+│     │                                                             │
+│     ├─► outer workspace A at /mnt/devhome                         │
+│     │     └─► inner devcontainer (bind) /home/<dev-user>          │
+│     │                                                             │
+│     ├─► outer workspace B at /mnt/devhome                         │
+│     │     └─► inner devcontainer (bind) /home/<dev-user>          │
+│     │                                                             │
+│     └─► outer workspace C at /mnt/devhome                         │
+│           └─► inner devcontainer (bind) /home/<dev-user>          │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+The volume lives in the **host** dockerd, above any individual workspace.
+It's defined in the Coder template as `docker_volume "devhome"`, scoped
+by `coder_workspace_owner.me.name`, and bind-mounted into the outer
+workspace container at `/mnt/devhome`. Each inner devcontainer then
+bind-mounts that path as its own `/home/<user>`, so the filesystem every
+workspace's IDE and shell see is literally the same volume.
+
+Properties that fall out of this layout:
+
+- Survives workspace deletion. Blowing away a workspace doesn't touch
+  `coder-<owner>-devhome`.
+- Survives `rebuild_no_cache`. That parameter only drops inner dockerd
+  state (`vsc-*` images + BuildKit cache) — not the host-level volume.
+- Nothing in `docs/migration-guide.md`'s volume name changes when you
+  rename a workspace. Identity is tied to the owner, not the workspace.
 
 ## What persists automatically
 
@@ -43,55 +84,78 @@ Any path under `$HOME`. A non-exhaustive list that matters for us:
 | `~/.local/`                   | pipx installs, user-local binaries                 |
 | `~/.config/`                  | Per-app config                                     |
 
-Nothing extra to configure. `SCCACHE_DIR` and `CLAUDE_CONFIG_DIR` default to
-paths under `$HOME`, so the env vars the old pattern used to override those
-are unnecessary and should be removed.
+Nothing extra to configure. `SCCACHE_DIR` and `CLAUDE_CONFIG_DIR` default
+to paths under `$HOME`, so the env vars the old pattern used to override
+them are unnecessary and should be removed.
 
 ## What doesn't persist
 
-- Anything **outside** `$HOME` — `/usr/local/...`, `/opt/...`, etc. These come
-  from the image, the Dockerfile, or feature installs. Rebuild the image to
-  change them.
-- The workspace folder itself (usually `/workspace`). This is bind-mounted
-  from the outer Coder workspace container's `/home/<coder>/<repo>`, which
-  has its own persistence (via the outer `docker_volume.home_volume` in the
-  Coder template). Your git working tree survives outer-workspace restarts;
-  inside the devcontainer it's the same filesystem surface.
+- Anything **outside** `$HOME` — `/usr/local/...`, `/opt/...`, etc. These
+  come from the image, the Dockerfile, or feature installs. Rebuild the
+  image to change them. This is also why our features install to
+  `/usr/local/bin` rather than `~/.local/bin`: feature-installed binaries
+  need to live outside the home volume.
+- The workspace folder itself (usually `/workspaces/<repo>`). That's the
+  git clone under the outer workspace's `/home/coder`, persisted by the
+  per-workspace `docker_volume.home_volume`. Your working tree survives
+  restarts of *its* workspace, but is scoped to that workspace.
+
+## Seeding on first create
+
+Bind mounts don't auto-seed from the image. The first time the per-owner
+volume is attached, it's empty, and the devcontainer's image-side
+`/home/<user>` (skeleton dotfiles, defaults from `/etc/skel`) is *not*
+copied into it automatically.
 
-## First-create seeding
+The `onCreateCommand` above handles seeding explicitly:
+
+```bash
+test -z "$(ls -A $HOME 2>/dev/null)" && cp -rT /etc/skel $HOME || true
+```
 
-When Docker mounts an empty named volume over a non-empty directory, it
-copies the image's directory contents into the volume. So the first time a
-user opens any devcontainer, the image's `/home/<user>` (skeleton dotfiles,
-defaults from `/etc/skel`) seeds the volume.
+- On the first-ever create for an owner, `$HOME` is empty → copy
+  `/etc/skel` in.
+- On every subsequent create (any workspace, any rebuild), `$HOME` has
+  content → no-op.
 
-After that, the volume wins. Subsequent rebuilds of the image will **not**
-propagate changes to the image's `$HOME` into the existing volume.
+After the first create the volume wins on its own. Subsequent rebuilds
+of the image will **not** propagate changes to the image's `$HOME` into
+the existing volume.
 
-Consequence: don't put long-lived shell config in `~/.bashrc` in the
-Dockerfile — it'd be stuck at whatever got seeded on first-create. Use
-`/etc/bash.bashrc` instead (system-wide, sourced by non-login interactive
-bashes on Debian/Ubuntu, image-owned, always authoritative).
+Consequence: don't put long-lived shell config in `~/.bashrc` via the
+Dockerfile — it'd be stuck at whatever got seeded on the first create.
+Use `/etc/bash.bashrc` instead (system-wide, sourced by non-login
+interactive bashes on Debian/Ubuntu, image-owned, always authoritative).
 
-## Cross-project side effects
+## Cross-workspace side effects
 
-One home for every devcontainer means:
+One home for every workspace means:
 
 - Pros: universal `~/.gitconfig`, `~/.ssh/*`, one Claude Code login, one
-  bash history, shared sccache/`~/.cargo` caches.
+  shared bash history, shared sccache / `~/.cargo` caches across all
+  projects the owner opens.
 - Cons: tools that write env-specific state to `$HOME` (some pyenv / nvm
   layouts, project-specific `~/.config/*` files) will leak between
   projects. For most dotfile-level state this is exactly what you want.
   If a specific tool misbehaves, override its config dir via `containerEnv`
-  to point at a project-scoped path under the repo.
+  to point at a project-scoped path under the repo's working tree.
+- Running two workspaces simultaneously means two processes writing to
+  the same home — the same situation as running two terminals on your
+  laptop. Tools that support concurrent writers (bash history with
+  `histappend`, content-addressed caches, atomic-rename lockfiles) cope
+  fine. Tools that don't (single-writer state files) behave as they would
+  locally.
 
 ## Resetting a home
 
 If the shared home gets into a bad state, nuke the volume from the host:
 
 ```bash
-docker volume rm devhome-<owner-username>
+docker volume rm coder-<owner-username>-devhome
 ```
 
-Next devcontainer start re-seeds it from the image. You'll need to
-re-login to Claude Code, re-set any interactive state, etc.
+Next devcontainer start sees an empty `/mnt/devhome`, the `onCreateCommand`
+re-seeds it from `/etc/skel`, and you're back to a clean home. You'll need
+to re-login to Claude Code, re-populate `~/.ssh` (the Coder sub-agent does
+this automatically via `coder_script "git_ssh_signing"`), and re-set any
+interactive state.