scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-09-30 01:51:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

feat(devcontainer): isolate host AI-CLI config via seed-once copies + persist claude-mem

Browse source 
Replace the read-write host bind mounts for the AI-CLI shareable dirs
(Claude skills/agents/memory/commands/plugins; Codex plugins/prompts/
memories/skills; Cursor rules/commands/agents/skills/plugins) with a
seed-once copy from a read-only /host/.<cli> stage into the per-container
config volume. The container gets its own writable copy and can never
write back to the host, closing the write-through vector where a
compromised in-container dependency could drop a malicious agent, command,
skill, or plugin onto the host for the next host session to auto-load.

Add a per-container claude-mem named volume (claude-mem-${devcontainerId})
at /home/node/.claude-mem, seeded once from a read-only /host/.claude-mem
stage. claude-mem's multi-GB SQLite + Chroma store is kept off a host bind
(unreliable fcntl locking / corruption risk over 9p on Docker Desktop
Windows) while still surviving rebuilds.

- post-create.sh: seed shareable dirs (marker-gated, seed-once) and run
  plugin-registry translation per seeded CLI; seed claude-mem behind a
  completion-sentinel guard that self-heals an interrupted multi-GB copy;
  chown the claude-mem volume only on first create.
- translate-plugin-registries.cjs: add selectRegistries() so translation
  runs per-CLI seed-once instead of clobbering container-installed plugins.
- ensure-host-config-dirs.cjs: add ~/.claude-mem; drop the shareable
  subdirs (no longer bind sources).
- devcontainer.json: drop the RW shareable binds; add the claude-mem
  volume + read-only stage.
- README: rewrite trust-boundary, mount table, and rebuild/reset docs for
  the copy model.
- tests: cover selectRegistries and the trimmed DIRS (30 pass).
This commit is contained in:
Gergo Magyar 2026-05-29 09:54:01 +01:00
parent d99149642f
commit 63a006e6dc
6 changed files with 421 additions and 257 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

165
.devcontainer/README.md
View file

@ -4,11 +4,11 @@ A cross-platform Dev Container that pre-installs Claude Code, OpenAI Codex CLI,
> ### ⚠️ Read this before using it on a work machine
>
> By **default this devcontainer shares your host AI-CLI config read-write.** A plugin, skill, agent, command, or memory you add on the host or inside the container appears on both sides — **and so does anything a compromised workspace dependency writes while running in the container.** Because `agents/`, `commands/`, `skills/`, and `rules/` are auto-loaded instruction/shell-executing surfaces, a single in-container compromise can land on your **host** and run in your next host CLI session, even after the container is gone. This is a deliberate trade-off for live config sync, **not** something the design prevents.
> This devcontainer **does not write to your host AI-CLI config.** Your skills, agents, commands, plugins, memory, prompts, and rules are **copied once** from a read-only host stage into a per-container volume on first create; the container edits its own copy and can never write back. So a compromised workspace dependency running in the container **cannot** drop a malicious agent, command, skill, or plugin onto your host for your next host CLI session to load — the write-through vector earlier versions had is closed. Your **credentials** (Claude/Codex/Cursor logins) likewise stay in per-container volumes and are never written back, and `~/.ssh`, `~/.aws`, `~/.azure`, `~/.config/gh`, and `~/.docker` are mounted **read-only**.
>
> What is **not** exposed that way: your **credentials** (Claude/Codex/Cursor logins) stay isolated in per-container volumes and are never written back to the host, and `~/.ssh`, `~/.aws`, `~/.azure`, `~/.config/gh`, and `~/.docker` are mounted **read-only** (readable, not writable from the container). There is **no egress firewall yet**, so a compromised dependency with read access also has the network to exfiltrate what it reads.
> What is **still** exposed: the read-only host stages (`/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`) and the read-only credential mounts are all **readable** inside the container. A compromised dependency can therefore READ your host CLI config, memory, SSH/cloud credentials, and GitHub token — and there is **no egress firewall yet**, so it has the network to exfiltrate what it reads. Read-only protects you from tampering and write-back, not from disclosure.
>
> If you don't want host↔container config sharing, use the isolated per-container-volume setup described in [§ Trust boundary, concretely](#trust-boundary-concretely) — you trade plugin/skill/memory sync for full isolation. Read that section in full before trusting this with credentials you couldn't afford to rotate.
> The trade-off of the copy model: host and container config **diverge after first create.** A skill or plugin you add on the host later won't appear in the container until you wipe the config volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). Edits you make inside the container persist across rebuilds but never reach the host.
## Quick start
@ -82,38 +82,40 @@ Open the repo folder in VS Code → **Reopen in Container**. The image is multi-
Same as macOS — open in VS Code and reopen in container. `updateRemoteUserUID: true` (default) shifts the container's `node` user UID/GID to match your host user, so bind-mounted files stay writable without extra setup.
## How CLI state is shared with your host
## How CLI state flows from your host
### AI CLIs (Claude Code, Codex, Cursor): direct RW bind for shareable content + per-container credentials
### AI CLIs (Claude Code, Codex, Cursor): copy-once from a read-only host stage + per-container credentials
The three AI CLIs use a **hybrid mount topology**: shareable subdirs/files (plugins, skills, agents, memory, commands, settings) are RW bind-mounted from host so reads AND writes go bidirectionally; credentials + identity stay in per-container named volumes so logging in/out in the container doesn't affect the host. Bind mounts at sub-paths override the named volume's content at those paths (Docker mount precedence — more specific path wins).
The three AI CLIs use a **copy-from-read-only-stage topology**: the host's `~/.<cli>` folders (and `~/.claude-mem`) are mounted **read-only** at `/host/.<cli>`, and `post-create.sh` copies out of them into per-container named volumes. Credentials, identity, and single config files are copied on **every** create; the shareable subdirs (plugins, skills, agents, memory, commands, prompts, rules) are copied **once** on first create and then owned by the container. Nothing is bind-mounted read-write into the host's CLI config, so the container can never modify your host setup. Session sub-paths overlay the config volume via their own named volumes (Docker mount precedence — more specific path wins).
| Mount | Source | Target | Mode | Purpose |
|---|---|---|---|---|
| Container Claude config dir | _named volume_ `claude-config-${devcontainerId}` | `/home/node/.claude` | rw | Per-container credentials + identity |
| Container Codex config dir | _named volume_ `codex-config-${devcontainerId}` | `/home/node/.codex` | rw | Per-container credentials |
| Container Cursor config dir | _named volume_ `cursor-config-${devcontainerId}` | `/home/node/.cursor` | rw | Per-container credentials |
| **Claude sessions** (overlay on the config volume) | _named volume_ `…-claude-sessions-${devcontainerId}` | `/home/node/.claude/projects` | rw | `--resume` transcripts; survives the `<cli>-config` volume wipe — see [Session resume](#session-resume-across-container-recreation) |
| **Codex sessions** | _named volume_ `…-codex-sessions-${devcontainerId}` | `/home/node/.codex/sessions` | rw | `codex resume` rollouts; SQLite index backfills on recreation |
| **Cursor sessions** | _named volumes_ `…-cursor-sessions-${devcontainerId}`, `…-cursor-projects-${devcontainerId}` | `/home/node/.cursor/chats`, `/home/node/.cursor/projects` | rw | `cursor-agent resume` store (best-effort — layout reverse-engineered) |
| Host Claude state, read-only stage | `$HOME/.claude` | `/host/.claude` | **read-only** | `post-create.sh` reads credentials + identity from here on container-create |
| Host Codex state, read-only stage | `$HOME/.codex` | `/host/.codex` | **read-only** | Same purpose for Codex |
| Host Cursor state, read-only stage | `$HOME/.cursor` | `/host/.cursor` | **read-only** | Same purpose for Cursor |
| **Claude shareable subdirs** (overlay on the volume) | `$HOME/.claude/{plugins/marketplaces,plugins/cache,skills,agents,memory,commands}` | same under `/home/node/.claude/` | rw | **Bidirectional** dir binds — install plugin on host or in container, both sides see it |
| **Codex shareable subdirs** | `$HOME/.codex/{plugins,prompts,memories,skills}` | same under `/home/node/.codex/` | rw | **Bidirectional** — whole `plugins/` dir bound (no path-bearing registry inside it) |
| **Cursor shareable subdirs** | `$HOME/.cursor/{plugins/marketplaces,plugins/local,rules,commands,agents,skills}` | same under `/home/node/.cursor/` | rw | **Bidirectional** — cursor-agent shares the Cursor 2.5 plugin/rules/commands surface |
| Mount | Source | Target | Mode | Purpose |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Container Claude config dir | _named volume_ `claude-config-${devcontainerId}` | `/home/node/.claude` | rw | Per-container credentials + identity |
| Container Codex config dir | _named volume_ `codex-config-${devcontainerId}` | `/home/node/.codex` | rw | Per-container credentials |
| Container Cursor config dir | _named volume_ `cursor-config-${devcontainerId}` | `/home/node/.cursor` | rw | Per-container credentials |
| **Claude sessions** (overlay on the config volume) | _named volume_ `…-claude-sessions-${devcontainerId}` | `/home/node/.claude/projects` | rw | `--resume` transcripts; survives the `<cli>-config` volume wipe — see [Session resume](#session-resume-across-container-recreation) |
| **Codex sessions** | _named volume_ `…-codex-sessions-${devcontainerId}` | `/home/node/.codex/sessions` | rw | `codex resume` rollouts; SQLite index backfills on recreation |
| **Cursor sessions** | _named volumes_ `…-cursor-sessions-${devcontainerId}`, `…-cursor-projects-${devcontainerId}` | `/home/node/.cursor/chats`, `/home/node/.cursor/projects` | rw | `cursor-agent resume` store (best-effort — layout reverse-engineered) |
| **claude-mem store** | _named volume_ `claude-mem-${devcontainerId}` | `/home/node/.claude-mem` | rw | claude-mem's SQLite DB + Chroma vector store; **seeded once** from `/host/.claude-mem`, then container-private — see note below |
| Host Claude state, read-only stage | `$HOME/.claude` | `/host/.claude` | **read-only** | `post-create.sh` reads credentials + identity from here on container-create |
| claude-mem store, read-only stage | `$HOME/.claude-mem` | `/host/.claude-mem` | **read-only** | `post-create.sh` seeds the claude-mem volume from here on first create |
| Host Codex state, read-only stage | `$HOME/.codex` | `/host/.codex` | **read-only** | Same purpose for Codex |
| Host Cursor state, read-only stage | `$HOME/.cursor` | `/host/.cursor` | **read-only** | Same purpose for Cursor |
| **Claude shareable subdirs** | _seeded into the config volume from_ `$HOME/.claude/{plugins/marketplaces,plugins/cache,skills,agents,memory,commands}` | same under `/home/node/.claude/` | n/a (copy) | **Seed-once** copy from the read-only stage; container owns its copy after |
| **Codex shareable subdirs** | _seeded from_ `$HOME/.codex/{plugins,prompts,memories,skills}` | same under `/home/node/.codex/` | n/a (copy) | **Seed-once** copy (whole `plugins/` dir — no path-bearing registry inside it) |
| **Cursor shareable subdirs** | _seeded from_ `$HOME/.cursor/{plugins/marketplaces,plugins/local,rules,commands,agents,skills}` | same under `/home/node/.cursor/` | n/a (copy) | **Seed-once** copy of the Cursor 2.5 plugin/rules/commands surface |
**What gets shared bidirectionally (RW dir bind from host):**
**What gets seeded once from the host (copy, not bind):**
- **Claude**: `plugins/marketplaces`, `plugins/cache`, `skills/`, `agents/`, `memory/`, `commands/`
- **Codex**: `plugins/` (whole dir — installed plugins land on host), `prompts/`, `memories/`, `skills/`
- **Codex**: `plugins/` (whole dir), `prompts/`, `memories/`, `skills/`
- **Cursor**: `plugins/marketplaces`, `plugins/local`, `rules/`, `commands/`, `agents/`, `skills/`
Install a plugin on the host or inside the container — both sides see it immediately. `/plugin marketplace add` from inside the container lands in your host `~/.<cli>/plugins/`, and `codex plugin add` / `cursor-agent` plugin installs write straight through to Windows. Save a memory from either side and it persists to the same host file.
On the **first** container-create, `post-create.sh` copies each of these out of the read-only `/host/.<cli>` stage into the per-container config volume, then writes a `.devcontainer-shareable-seeded` marker. On every later rebuild the marker is present, so the copy is skipped and the container keeps whatever it has accumulated. A plugin/skill/agent you install **inside** the container persists across rebuilds; one you add on the **host** after first create won't appear in the container until you remove the config volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). Nothing here is writable back to the host — `/plugin marketplace add` inside the container installs into the container's own volume copy, not your host `~/.<cli>/plugins/`.
**Single config files are copied on container-create, not bind-mounted** — on Docker Desktop Windows a single-file bind is 9p while the named volume is ext4, and atomic config writes (`tmp` → rename onto target) trip EXDEV (this is what caused Codex's `config/batchWrite failed in TUI`). So these are synced from host on rebuild and the container rewrites its own copy until the next rebuild: `settings.json` + `$HOME/.claude.json` (Claude), `config.toml` (Codex), `cli-config.json` + `mcp.json` (Cursor). `hooks.json` (Cursor) is deliberately **not** synced — Cursor hooks execute shell commands, so sharing them would widen the supply-chain attack surface; add it yourself if you want it.
**Plugin registry files with absolute paths are translated, not shared** — Claude's `known_marketplaces.json` / `installed_plugins.json` / `plugin-catalog-cache.json` and Cursor's `installed_plugins.json` bake in `C:\Users\…` (Windows) or `/Users/…` (macOS) install paths. `post-create.sh` rewrites those to `/home/node/.<cli>/plugins/…` and writes the result into the named volume, so plugins resolve inside Linux instead of failing with `cache-miss`. Codex needs no translation — its enablement registry is `config.toml` (git URLs + logical keys, no filesystem paths), which is why its whole `plugins/` dir can be bound directly.
**Plugin registry files with absolute paths are translated, not copied verbatim** — Claude's `known_marketplaces.json` / `installed_plugins.json` / `plugin-catalog-cache.json` and Cursor's `installed_plugins.json` bake in `C:\Users\…` (Windows) or `/Users/…` (macOS) install paths. `post-create.sh` rewrites those to `/home/node/.<cli>/plugins/…` and writes the result into the named volume, so plugins resolve inside Linux instead of failing with `cache-miss`. This translation is **also seed-once per CLI** — it runs only for a CLI being seeded that create (`translate-plugin-registries.cjs claude cursor`), so it stays consistent with the seed-once `cache/` copy and won't overwrite a plugin you installed inside the container on a later rebuild. Codex needs no translation — its enablement registry is `config.toml` (git URLs + logical keys, no filesystem paths), so its whole `plugins/` dir is copied as-is.
**What stays per-container (in the named volume) and is synced from host on container-create:**
@ -126,48 +128,50 @@ Install a plugin on the host or inside the container — both sides see it immed
- Host has no credentials → `claude login` / `codex login --device-auth` / `cursor-agent login` inside container; credentials stay in the named volume across rebuilds (volume is keyed by `${devcontainerId}`, stable for the workspace path).
- `claude logout` inside container clears volume credentials only; host is untouched.
**Why CLAUDE_CONFIG_DIR is intentionally NOT set:** Claude's default `~/.claude` matches the named-volume mount target, so the env var added no behavior — but setting it changed which file Claude reads `hasCompletedOnboarding` from. With it set, Claude reads `$CLAUDE_CONFIG_DIR/.claude.json` (the small identity-only file) and re-onboards every container; without it, Claude reads `$HOME/.claude.json` (now bind-mounted from host, with `hasCompletedOnboarding: true`).
**Why CLAUDE_CONFIG_DIR is intentionally NOT set:** Claude's default `~/.claude` matches the named-volume mount target, so the env var added no behavior — but setting it changed which file Claude reads `hasCompletedOnboarding` from. With it set, Claude reads `$CLAUDE_CONFIG_DIR/.claude.json` (the small identity-only file) and re-onboards every container; without it, Claude reads `$HOME/.claude.json` (copied from the read-only `/host/.claude.json` stage on container-create via `seed-claude-config.cjs`, with `hasCompletedOnboarding: true`).
**Trade-off accepted: write-through to host CLI config.** A compromised npm package in the workspace dep tree, running inside the container, can write to `~/.claude/plugins/`, `~/.claude/agents/`, `~/.claude/memory/`, etc. on host. The next host Claude session would auto-load whatever it dropped. This is the explicit cost of the bidirectional RW bind. The alternative (read-only stage + symlinks) made `/plugin marketplace add` inside the container fail with EROFS — unacceptable. Credentials stay in the per-container named volume, so an attacker has to compromise the OAuth-bearing file specifically in container to get them; the volume isn't shared back to host.
**Host CLI config is protected from write-through.** The shareable dirs are copied out of a **read-only** stage into the container's own volume, so a compromised npm package in the workspace dep tree — running inside the container — **cannot** write a malicious agent, command, skill, or plugin back to `~/.claude/`, `~/.codex/`, or `~/.cursor/` on the host. The earlier design bind-mounted these read-write and accepted that write-through as the cost of live sync; this design closes it. An even earlier alternative (read-only stage + symlinks) made `/plugin marketplace add` inside the container fail with EROFS; copying into a writable volume avoids that, because the container writes to its own copy rather than a read-only mount. What a compromised dependency can still do is **read** the read-only host stages (`/host/.<cli>`, `/host/.claude-mem`) and the read-only credential mounts and exfiltrate them — there is [no egress firewall yet](#whats-not-included-yet). The cost of the copy model is **divergence**: host edits made after first create don't reach the container until you wipe the config volume and rebuild.
**Refresh-token divergence between rebuilds.** Container's credentials match host's at container-create time; after that, container manages its own refresh until the next rebuild. Anthropic rotates refresh tokens on every use, so an unattended container that hasn't talked to the API in weeks can hit a silent 401 if the host has refreshed since. Re-run `claude login` inside the container, or rebuild, to recover.
**claude-mem is seeded once, then container-private.** The [claude-mem](https://github.com/thedotmack/claude-mem) store (`$HOME/.claude-mem` — a multi-GB SQLite DB `claude-mem.db` + `-wal`/`-shm`, plus a Chroma vector store `chroma/chroma.sqlite3` and its HNSW index binaries) is the one shareable-looking folder that is **deliberately not a host bind**, for the same SQLite reason as sessions below: a multi-GB WAL database over the 9p/virtiofs bind risks unreliable `fcntl` locking and corruption — sharply so if claude-mem ran on the host and in the container against the same DB at once. So it gets its own per-container named volume (`claude-mem-${devcontainerId}`), and `post-create.sh` **seeds it once** from the read-only `/host/.claude-mem` stage _only when the volume has no DB yet_. The first container-create copies the host's store in (a one-time copy, possibly several GB); every later rebuild keeps whatever the container accumulated and skips the copy. The container's memory and the host's **diverge from that seed point** — writes do not flow back — which is the price of keeping SQLite off a shared bind. To re-seed from the host's current store, remove the volume (`docker volume rm claude-mem-<id>`) and rebuild. `ensure-host-config-dirs.cjs` creates an empty `~/.claude-mem` on hosts that never installed claude-mem, so the read-only stage bind always resolves; the seed then finds no DB and the container simply starts with empty memory.
### Session resume across container recreation
`claude --resume`, `codex resume`, and `cursor-agent resume` all read **local** transcript files. Those live *inside* each CLI's config dir, which is a per-container named volume — so they already survive an ordinary **Rebuild Container**. What they did *not* survive were the very things this README tells you to do: `docker volume rm <cli>-config-${devcontainerId}` to force a re-login or clear an `EACCES`, a `${devcontainerId}` change, or a full delete-and-recreate. Each of those drops the config volume and takes your session history with it.
`claude --resume`, `codex resume`, and `cursor-agent resume` all read **local** transcript files. Those live _inside_ each CLI's config dir, which is a per-container named volume — so they already survive an ordinary **Rebuild Container**. What they did _not_ survive were the very things this README tells you to do: `docker volume rm <cli>-config-${devcontainerId}` to force a re-login or clear an `EACCES`, a `${devcontainerId}` change, or a full delete-and-recreate. Each of those drops the config volume and takes your session history with it.
So the resume/transcript directories get their **own** named volumes (mount group 6 in `devcontainer.json`), keyed like the `node_modules` volumes (`${localWorkspaceFolderBasename}-…-${devcontainerId}`) and mounted *over* the config volume at the session sub-paths:
So the resume/transcript directories get their **own** named volumes (mount group 6 in `devcontainer.json`), keyed like the `node_modules` volumes (`${localWorkspaceFolderBasename}-…-${devcontainerId}`) and mounted _over_ the config volume at the session sub-paths:
| Resume command | Persisted volume → target | What's stored |
|---|---|---|
| `claude --resume` / `--continue` | `…-claude-sessions-…` → `~/.claude/projects` | `<encoded-cwd>/<uuid>.jsonl` transcripts + `sessions-index.json`. Container cwd is always `/workspace`, so only that slice is stored. Pure JSONL/JSON — no SQLite. |
| `codex resume` / `resume --last` | `…-codex-sessions-…` → `~/.codex/sessions` | `YYYY/MM/DD/rollout-*.jsonl`. The `state_5.sqlite` thread index stays on the config volume (a single WAL file we don't split out); when it's absent after a recreation, Codex rebuilds it from these rollouts on the next start (a one-time backfill). |
| `cursor-agent resume` / `ls` | `…-cursor-sessions-…` → `~/.cursor/chats`; `…-cursor-projects-…` → `~/.cursor/projects` | `chats/{hash}/{uuid}/store.db` (one SQLite db per session, each in its own dir) + `projects/.../agent-transcripts`. cursor-agent's layout is reverse-engineered, so treat this as best-effort. |
| Resume command | Persisted volume → target | What's stored |
| -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `claude --resume` / `--continue` | `…-claude-sessions-…` → `~/.claude/projects` | `<encoded-cwd>/<uuid>.jsonl` transcripts + `sessions-index.json`. Container cwd is always `/workspace`, so only that slice is stored. Pure JSONL/JSON — no SQLite. |
| `codex resume` / `resume --last` | `…-codex-sessions-…` → `~/.codex/sessions` | `YYYY/MM/DD/rollout-*.jsonl`. The `state_5.sqlite` thread index stays on the config volume (a single WAL file we don't split out); when it's absent after a recreation, Codex rebuilds it from these rollouts on the next start (a one-time backfill). |
| `cursor-agent resume` / `ls` | `…-cursor-sessions-…` → `~/.cursor/chats`; `…-cursor-projects-…` → `~/.cursor/projects` | `chats/{hash}/{uuid}/store.db` (one SQLite db per session, each in its own dir) + `projects/.../agent-transcripts`. cursor-agent's layout is reverse-engineered, so treat this as best-effort. |
Because these are **separate** volumes from `<cli>-config-${devcontainerId}`, the re-login fix (`docker volume rm claude-config-…`) no longer destroys your sessions — that was the point.
**Survives:** Rebuild Container, Rebuild Without Cache, a full delete-and-recreate of the container, and the `docker volume rm <cli>-config-…` re-login / `EACCES` fix.
**Does *not* survive** (same durability tier as the `node_modules` volumes): `docker volume prune`, a `${devcontainerId}` change (moving the checkout to a new path, or switching between Windows-native and WSL2), or moving to a new machine. To deliberately wipe sessions, remove the session volumes too — see [Rebuild / reset](#rebuild--reset). Two checkouts with the **same folder name** on one host would share session volumes only if they also share a `${devcontainerId}`; they don't, so they stay separate.
**Does _not_ survive** (same durability tier as the `node_modules` volumes): `docker volume prune`, a `${devcontainerId}` change (moving the checkout to a new path, or switching between Windows-native and WSL2), or moving to a new machine. To deliberately wipe sessions, remove the session volumes too — see [Rebuild / reset](#rebuild--reset). Two checkouts with the **same folder name** on one host would share session volumes only if they also share a `${devcontainerId}`; they don't, so they stay separate.
**First rebuild after adopting this, one-time:** if a container created *before* these volumes existed already had sessions on the config volume (`~/.claude/projects`, `~/.codex/sessions`, …), the new empty session volume mounts *over* that sub-path and **masks** the old content — same Docker-precedence shadowing described for plugins above. The old sessions are hidden, not deleted. To carry them forward once, copy them out of the config volume into the session volume; or just start fresh — new sessions land on the session volume from then on.
**First rebuild after adopting this, one-time:** if a container created _before_ these volumes existed already had sessions on the config volume (`~/.claude/projects`, `~/.codex/sessions`, …), the new empty session volume mounts _over_ that sub-path and **masks** the old content — same Docker-precedence shadowing described for plugins above. The old sessions are hidden, not deleted. To carry them forward once, copy them out of the config volume into the session volume; or just start fresh — new sessions land on the session volume from then on.
**Why volumes and not host bind mounts (like plugins).** Plugins/skills/agents are bind-mounted to the host so they sync both ways. Sessions are deliberately *not*, because a transcript can contain anything you pasted or the agent read — API keys, file contents, connection strings. Putting them on the host would (a) spill that to host disk, (b) add them to the in-container write-through surface a compromised dependency can reach (there's still [no egress firewall](#whats-not-included-yet)), and (c) leak *every other project's* transcripts into the container (Codex `sessions/` and Cursor `chats/` aren't project-scoped). Container-private volumes avoid all three while still surviving recreation. And Claude/Codex transcripts embed the container cwd (`/workspace`), so even if you *did* bind them to the host, the host CLI wouldn't natively `--resume` them — its encoded-cwd folder differs.
**Why sessions are container-private and not even seeded from the host.** The shareable config dirs are _seeded once_ from the host (you want your skills/agents/plugins in the container). Sessions are deliberately _not_ seeded and never touch the host, because a transcript can contain anything you pasted or the agent read — API keys, file contents, connection strings. Binding or copying them to/from the host would (a) spill that to host disk, (b) add a write-through surface a compromised dependency can reach (there's still [no egress firewall](#whats-not-included-yet)), and (c) leak _every other project's_ transcripts into the container (Codex `sessions/` and Cursor `chats/` aren't project-scoped). Container-private volumes avoid all three while still surviving recreation. And Claude/Codex transcripts embed the container cwd (`/workspace`), so even if you _did_ bind them to the host, the host CLI wouldn't natively `--resume` them — its encoded-cwd folder differs.
**Opt in to host-shared sessions anyway.** If you want transcripts visible/portable on the host and accept the trade-offs above, uncomment the host-bind block in `devcontainer.json` (just below the group-6 volumes) and add the matching source dirs to `ensure-host-config-dirs.cjs`'s `DIRS` so Docker can resolve the binds. That block scopes Claude to `/workspace`'s encoded subdir to limit the cross-project leak; the Codex and Cursor stores can't be scoped that way, so they expose every project's transcripts.
### Other host bind mounts
| Container path | Host source | Mode | Why |
|---|---|---|---|
| `~/.config/git` | `$HOME/.config/git` | **read-only** | XDG-style git config / ignore / attributes |
| `~/.ssh` | `$HOME/.ssh` | **read-only** | SSH commit signing + git push over SSH |
| `~/.config/gh` | `$HOME/.config/gh` | **read-only** | `gh` CLI auth (PR/issue create, checks) — container reads your existing host login |
| `~/.docker` | `$HOME/.docker` | **read-only** | Container registry auth + buildx config (inert until you add Docker CLI via a Feature) |
| `~/.aws` | `$HOME/.aws` | **read-only** | AWS CLI / SDK credentials (forward-compat — empty by default) |
| `~/.azure` | `$HOME/.azure` | **read-only** | Azure CLI credentials (forward-compat — empty by default) |
| Container path | Host source | Mode | Why |
| --------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------- |
| `~/.config/git` | `$HOME/.config/git` | **read-only** | XDG-style git config / ignore / attributes |
| `~/.ssh` | `$HOME/.ssh` | **read-only** | SSH commit signing + git push over SSH |
| `~/.config/gh` | `$HOME/.config/gh` | **read-only** | `gh` CLI auth (PR/issue create, checks) — container reads your existing host login |
| `~/.docker` | `$HOME/.docker` | **read-only** | Container registry auth + buildx config (inert until you add Docker CLI via a Feature) |
| `~/.aws` | `$HOME/.aws` | **read-only** | AWS CLI / SDK credentials (forward-compat — empty by default) |
| `~/.azure` | `$HOME/.azure` | **read-only** | Azure CLI credentials (forward-compat — empty by default) |
**Why everything here is read-only — including `gh`/`docker`:** `ssh`/`aws`/`azure` are consumed read-only by their clients (the SSH client and the AWS/Azure SDKs only read their credential files), so a one-way mount loses nothing. `gh` and `docker` *can* write their own state (`gh auth login` / `gh auth refresh` rewrite `hosts.yml`; `docker login` / buildx write `config.json`), so they were originally read-write — but that also lets a compromised in-container dependency rewrite your host `~/.config/gh/hosts.yml` (swap your GitHub token) or `~/.docker/config.json` (point a `credHelper` at an attacker-controlled binary), which is a credential-takeover vector, not just a read. Since the common case is *reading* an existing host login, both are mounted **read-only**: `gh pr create`, `gh pr checks`, and registry pulls/pushes using your host creds all still work — only a `gh auth login` / `docker login` run **inside** the container won't persist back to the host. Re-run those on the host, or, if you specifically want in-container logins to stick, drop `,readonly` from the `~/.config/gh` and `~/.docker` mounts in `devcontainer.json`.
**Why everything here is read-only — including `gh`/`docker`:** `ssh`/`aws`/`azure` are consumed read-only by their clients (the SSH client and the AWS/Azure SDKs only read their credential files), so a one-way mount loses nothing. `gh` and `docker` _can_ write their own state (`gh auth login` / `gh auth refresh` rewrite `hosts.yml`; `docker login` / buildx write `config.json`), so they were originally read-write — but that also lets a compromised in-container dependency rewrite your host `~/.config/gh/hosts.yml` (swap your GitHub token) or `~/.docker/config.json` (point a `credHelper` at an attacker-controlled binary), which is a credential-takeover vector, not just a read. Since the common case is _reading_ an existing host login, both are mounted **read-only**: `gh pr create`, `gh pr checks`, and registry pulls/pushes using your host creds all still work — only a `gh auth login` / `docker login` run **inside** the container won't persist back to the host. Re-run those on the host, or, if you specifically want in-container logins to stick, drop `,readonly` from the `~/.config/gh` and `~/.docker` mounts in `devcontainer.json`.
`~/.gitconfig` is **not** bind-mounted — VS Code's Dev Containers extension auto-copies the host's gitconfig into the container at attach time (this is built-in behavior, not something this devcontainer configures). The bind-mount approach conflicts with that auto-copy mechanism, so we let VS Code own it. The end result is the same: your host's `user.name` / `user.email` are available inside the container.
@ -180,9 +184,9 @@ If a host source dir doesn't exist when the container is first created, the `ini
- **Cursor CLI inside containers** has [known upstream auth issues](https://forum.cursor.com/t/cursor-agent-authentication-issue-inside-docker/143995) — even with a correctly-synced `cli-config.json`, you may need to re-run `cursor-agent login` inside the container.
- **Stale named volumes from old rebuilds can carry forward.** If you delete and re-create the same workspace, or if a prior container left interim state with a different `userID`, deleting the named volumes before rebuild guarantees a clean sync: `docker volume rm claude-config-${devcontainerId} codex-config-${devcontainerId} cursor-config-${devcontainerId}` (look them up with `docker volume ls | grep -config-`).
- **User-scope MCP servers with absolute host paths won't resolve in-container.** `~/.claude.json` (Claude), `~/.codex/config.toml` (Codex), and `~/.cursor/mcp.json` (Cursor) are copied from host on container-create, so their user-scope `mcpServers` entries come along. But an entry whose `command` is an absolute host path (`C:\tools\foo.exe`, `/usr/local/bin/foo`) points at a binary that doesn't exist in the container — that server silently fails to launch. Only registry/`npx`-based servers (like this repo's `.mcp.json`, which uses `npx -y gitnexus@latest mcp`) and remote/URL servers work unchanged. The path-translation pass only rewrites `*/.​<cli>/plugins/*` registry paths, **not** arbitrary `mcpServers` command paths (there's no correct container target for a host-local binary). Install such MCP servers inside the container, or use `npx`/remote ones.
- **User-scope config is synced once per container-create, then diverges.** A `mcpServers` entry, plugin enable, or setting you add **on the host after** the container was created is not visible in the container until the next rebuild (these files are copy-on-create, not bind-mounted — single-file binds trip EXDEV on Docker Desktop Windows). Rebuild to pick up host-side config changes. Shareable *dirs* (plugins/skills/agents/memory/commands) are live-bound and do not have this lag.
- **Plugins installed in-container before a host install get shadowed on rebuild.** If you ran `/plugin marketplace add` (or `codex plugin add`) inside the container while the matching host dir was empty, the extracted files landed in the named volume. On the next rebuild the (empty) host bind mount overlays that sub-path and the volume content becomes invisible (masked, not deleted — Docker mount precedence). The plugins appear to vanish. Recovery: re-run the install (it now writes through to the host), or install on the host. Installing on the host is the durable path since the host dir is the bind source.
- **Plugin installs are single-writer across checkouts.** `${devcontainerId}` isolates each container's *credential volume*, but the host plugin dirs (`~/.<cli>/plugins/...`) are the **one** shared bind source across every GitNexus checkout and every running container. Two containers running `/plugin marketplace add` / `codex plugin add` against the same host dir simultaneously can interleave their git clones/extractions. Install plugins from one container (or the host) at a time — same single-writer expectation as `gitnexus analyze` against a shared `.gitnexus/`.
- **Host config is seeded once per devcontainer, then diverges — this now applies to everything.** A `mcpServers` entry, setting, plugin, skill, agent, or command you add **on the host after** the container was created is not visible in the container until you remove the config volume and rebuild. Single config files (`mcpServers`, `settings.json`, …) are copy-on-create; the shareable dirs (plugins/skills/agents/memory/commands/prompts/rules) are copy-on-**first**-create (they persist across ordinary rebuilds and aren't even re-copied). Both diverge from the host after their copy. To pull host-side changes in, wipe the relevant volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)).
- **Plugins/skills/agents installed in-container persist; they do not reach the host.** A `/plugin marketplace add` (or `codex plugin add`, or a new skill/agent) inside the container writes to the container's own config volume and survives ordinary rebuilds. It never appears on the host — the host dirs are read-only sources, not bind targets. To get a plugin onto the host, install it on the host (then wipe + rebuild to seed it into the container).
- **No cross-checkout plugin contention.** Because each container copies plugins into its own per-`${devcontainerId}` volume rather than sharing one host bind source, two containers (or checkouts) installing plugins at the same time no longer interleave git clones/extractions against a shared host dir. Each writes only its own copy.
### What you still don't have inside the container
@ -195,30 +199,30 @@ These are commonly-needed CLIs that aren't installed by default — adding them
That means:
- **Authentication is shared.** If you're already logged in on the host (`claude login`, `codex login`, `cursor-agent login`, `gh auth login`), you're already logged in inside the container. No second login step.
- **Plugins, skills, agents, memory, and commands sync both ways, live.** Install a plugin from inside the container and it shows up on the host; add a custom agent on the host and the container sees it immediately. The memory store at `~/.claude/memory/` is the same file tree from both sides. (`settings.json` and the user-scope `~/.claude.json` are *not* in this live set — they're copy-on-create, so host edits to them need a rebuild; see the quirks above. `~/.claude/projects/` is container-local by design, so per-project trust/history don't leak between host and container.)
- **Plugins, skills, agents, memory, and commands are seeded from the host once, then container-private.** On first create the container copies your host's plugins/skills/agents/memory/commands (and Codex prompts/memories, Cursor rules) into its own volume. After that they're independent: install or edit inside the container and it stays in the container (persists across rebuilds); add a plugin or agent on the host and the container won't see it until you wipe the config volume and rebuild. Nothing the container does reaches the host. (`settings.json` and the user-scope `~/.claude.json` are copy-on-create the same way; `~/.claude/projects/` is container-local by design.)
- **Git identity comes from the host.** Commits from inside the container use your host's `user.name` / `user.email` — VS Code's Dev Containers extension auto-copies your `~/.gitconfig` into the container at attach time. Any XDG-style config under `~/.config/git/` flows through via the read-only bind mount. To change git identity, edit `~/.gitconfig` on the host (container-side `git config --global` writes to a container-local file that's discarded on rebuild).
- **SSH keys flow through (read-only).** Push over SSH remotes and SSH commit signing work inside the container using your host keys. The mount is read-only so container code can't exfiltrate or modify private keys — agent-perspective, this means you get git operations but the keys stay vendor-side.
- **`gh` auth is shared.** `gh pr create`, `gh pr checks`, `gh issue create` work inside the container without re-authenticating.
- **No per-workspace duplication.** All your devcontainers across all your projects see the same host CLI state, just like all your host shells do.
The bind mount source directories are guaranteed to exist by the `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`), which runs on the host before container create. It's a Node script (not a shell one-liner) so the same command works on Windows `cmd.exe` and POSIX shells, and it creates the full set of bind-mount source dirs — all the `~/.claude`, `~/.codex`, `~/.cursor` shareable subdirs plus `~/.ssh`, `~/.docker`, `~/.aws`, `~/.azure`, `~/.config/{gh,git}` — not just the top-level CLI dirs.
The bind mount source directories are guaranteed to exist by the `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`), which runs on the host before container create. It's a Node script (not a shell one-liner) so the same command works on Windows `cmd.exe` and POSIX shells. It creates the top-level bind-mount source dirs — `~/.claude`, `~/.codex`, `~/.cursor`, `~/.claude-mem`, plus `~/.ssh`, `~/.docker`, `~/.aws`, `~/.azure`, `~/.config/{gh,git}`. It deliberately does **not** pre-create the shareable subdirs (skills/agents/plugins/…): those are no longer bind sources (they're copied out of the whole-`~/.<cli>` read-only stage), and pre-creating empty ones would needlessly write into the host of someone who never used that CLI.
### Trust boundary, concretely
Host and container share a single trust boundary by design — fine for personal-dev, but the consequence is concrete. Any malicious npm package or `postinstall` script in the workspace dep tree, running inside the container, has direct **read** access to:
- **Host AI CLI state** — the read-only stage at `/host/.claude`, `/host/.codex`, `/host/.cursor` (credentials + identity), **and** the read-write-bound shareable dirs (plugins, skills, agents, memory, commands, etc.) which ARE your host directories
- **Host AI CLI state** — the read-only stage at `/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`, which exposes your **entire** host `~/.<cli>` tree (credentials, identity, AND the shareable skills/agents/plugins/memory/commands) for _reading_. The container copies what it needs out of this stage; a compromised dep can read all of it. It is read-only, so none of it can be written back
- The **container's own credential snapshots** at `/home/node/.claude/.credentials.json` etc. (copied from host on container-create)
- `~/.claude/memory/` / per-project memory (which may contain user-stored secrets if you've used the `/remember` skill)
- The **current container's own session transcripts** (`~/.claude/projects`, `~/.codex/sessions`, `~/.cursor/chats`/`projects` — the group-6 volumes), which can hold anything pasted into or read during a session. These are container-private (see one-way note below), so this is read access to *this* container's sessions only, not the host's or other projects'
- The **current container's own session transcripts** (`~/.claude/projects`, `~/.codex/sessions`, `~/.cursor/chats`/`projects` — the group-6 volumes), which can hold anything pasted into or read during a session. These are container-private (see one-way note below), so this is read access to _this_ container's sessions only, not the host's or other projects'
- Your **`gh` token** (`~/.config/gh`)
- Your **SSH private keys** (`~/.ssh/`)
- Docker registry tokens in **`~/.docker/config.json`** (if you've `docker login`-ed)
- AWS/Azure CLI credentials if you've populated `~/.aws/` or `~/.azure/`
It also has **write-through** to host for the shareable dirs — this is the deliberate cost of bidirectional plugin/skill/memory sync, **not** something the design prevents. A compromised in-container dep CAN write into your host `~/.claude/{plugins,agents,skills,commands,memory}/`, `~/.codex/{plugins,prompts,memories,skills}/`, and `~/.cursor/{plugins,rules,commands,agents,skills}/`. Because several of those (agents, commands, skills, rules) are instruction/shell-executing surfaces an agent auto-loads, that write-through means a single in-container compromise can persist across container teardown and run in your next **host** session. The only deliberately-withheld auto-executing surface is Cursor's `hooks.json` (synced read-only via copy-on-create, never bound) because hooks fire without an agent invoking them — but that is a narrowing of the surface, not a closed boundary.
It does **not** have write-through to the host's CLI config. The shareable dirs are copied out of the read-only stage into the container's own volume, so a compromised in-container dep **cannot** write into your host `~/.claude/{plugins,agents,skills,commands,memory}/`, `~/.codex/{plugins,prompts,memories,skills}/`, or `~/.cursor/{plugins,rules,commands,agents,skills}/`. The persistence vector earlier versions had — drop a malicious auto-loaded agent/command/skill/rule onto the host, have it run in your next **host** session — is closed: there is no writable path from the container to those host folders. (Cursor's `hooks.json` is still additionally withheld from even the _container's_ copy, because hooks fire without an agent invoking them.) The boundary is now one-way for **all** of the host CLI config, not just credentials.
**What stays one-way (genuinely protected):** credentials never flow back to host — `.credentials.json` / `auth.json` / `cli-config.json` live only in the per-container named volumes, and the `/host/.<cli>` stage they're copied from is mounted **read-only**, so the snapshot can't be overwritten back. `~/.ssh`, `~/.config/git`, `~/.aws`, `~/.azure`, **`~/.config/gh`, and `~/.docker`** are read-only binds with the same one-way property — readable but not writable from the container, so a compromised dep can *read* your `gh`/registry tokens but cannot *rewrite* them to hijack your future host auth. If you need the shareable AI-CLI dirs to be one-way too, switch them from `type=bind` to copy-on-create (or to named volumes — see the enterprise note below). **Session transcripts are already on the protected side:** they live in per-workspace named volumes (mount group 6), so a compromised dependency can read *this* container's sessions but they are never written back to the host and the container can't see any *other* project's transcripts. The opt-in host-bind block in `devcontainer.json` reverses that — only enable it if you accept transcripts on host disk; see [Session resume across container recreation](#session-resume-across-container-recreation).
**What stays one-way (genuinely protected):** everything. Credentials never flow back to host — `.credentials.json` / `auth.json` / `cli-config.json` live only in the per-container named volumes, and the `/host/.<cli>` stage they're copied from is mounted **read-only**, so the snapshot can't be overwritten back. The shareable AI-CLI dirs (skills/agents/plugins/memory/commands/prompts/rules) are now copy-on-create from that same read-only stage, so they have the one-way property too — readable for the copy, never writable back. `~/.ssh`, `~/.config/git`, `~/.aws`, `~/.azure`, **`~/.config/gh`, and `~/.docker`** are read-only binds with the same property — a compromised dep can _read_ your `gh`/registry tokens but cannot _rewrite_ them to hijack your future host auth. **Session transcripts** live in per-workspace named volumes (mount group 6) and are never seeded from or written back to the host, and the container can't see any _other_ project's transcripts. The opt-in host-bind block in `devcontainer.json` reverses that for sessions only — enable it only if you accept transcripts on host disk; see [Session resume across container recreation](#session-resume-across-container-recreation).
**The egress firewall is the key compensating control that is still missing.** It's deferred (see "What's not included (yet)" below), so a compromised package currently has unrestricted outbound network to exfiltrate anything in the read list above. Until it lands, treat that read surface as exposed to any code you run in the container — don't use this devcontainer on a machine whose host credentials you couldn't afford to rotate. The isolated-volume setup below removes host AI-CLI config/credentials from that surface entirely.
@ -229,7 +233,7 @@ It also has **write-through** to host for the shareable dirs — this is the del
- Cursor: dashboard → Integrations, rotate API key + revoke CLI session
- GitHub: `gh auth refresh` or revoke the token at github.com/settings/tokens
For high-trust enterprise environments where host and container should NOT share credentials, swap the three CLI bind mounts (`~/.claude`, `~/.codex`, `~/.cursor`) in `.devcontainer/devcontainer.json` for `type=volume` named volumes (Anthropic's reference pattern). You give up host plugin/skill/memory sync in exchange for credential isolation per devcontainer.
For high-trust enterprise environments where the container should not even be able to **read** host CLI state, remove the three read-only stage binds (`/host/.claude`, `/host/.codex`, `/host/.cursor`) — plus `/host/.claude-mem` and `/host/.claude.json` — from `.devcontainer/devcontainer.json`. With no stage to copy from, `post-create.sh`'s seed and credential-sync steps quietly do nothing (their `[ -f ]` / `[ -d ]` guards), and each devcontainer starts with empty, fully isolated config and credentials (Anthropic's reference pattern). You give up seeding your host setup into the container in exchange for removing host config/credentials from the container's read surface entirely; log in inside each container instead.
## First-time CLI authentication
@ -272,11 +276,11 @@ Verify any time with `cursor-agent status`.
For non-interactive use (CI runners, automated scripts), all three CLIs accept API keys via env vars:
| CLI | Env var | Where to get the key |
|---|---|---|
| CLI | Env var | Where to get the key |
| ----------- | ------------------- | --------------------------------------------- |
| Claude Code | `ANTHROPIC_API_KEY` | <https://console.anthropic.com/settings/keys> |
| Codex | `OPENAI_API_KEY` | <https://platform.openai.com/api-keys> |
| Cursor | `CURSOR_API_KEY` | Cursor dashboard → Integrations |
| Codex | `OPENAI_API_KEY` | <https://platform.openai.com/api-keys> |
| Cursor | `CURSOR_API_KEY` | Cursor dashboard → Integrations |
These env vars are intentionally **not** injected into the container from the host. `${localEnv:VAR}` resolves an unset host variable to an empty string, and some CLIs (Cursor in particular) treat a set-but-empty key as "use this key" rather than "fall back to stored login" — which would silently break the login flow for everyone who hasn't pre-set the host var.
@ -293,11 +297,11 @@ A non-empty API key env var takes precedence over stored login credentials for e
## Port forwarding
| Port | Service | Notes |
|------|---------|-------|
| `5173` | Vite dev server (`gitnexus-web`) | Auto-forwarded with notification |
| `4747` | `gitnexus serve` HTTP API | **Must not be remapped** — `gitnexus-web` hardcodes `http://localhost:4747` as the default backend URL |
| `4173` | Static web (Vite preview) | Silently forwarded |
| Port | Service | Notes |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `5173` | Vite dev server (`gitnexus-web`) | Auto-forwarded with notification |
| `4747` | `gitnexus serve` HTTP API | **Must not be remapped** — `gitnexus-web` hardcodes `http://localhost:4747` as the default backend URL |
| `4173` | Static web (Vite preview) | Silently forwarded |
VS Code's Ports panel shows forwarded ports once their listener starts.
@ -314,11 +318,12 @@ VS Code's Ports panel shows forwarded ports once their listener starts.
- **Rebuild Container** (Command Palette) — re-runs the Dockerfile build and `postCreateCommand` against the existing named volumes (auth, history, **and sessions** persist).
- **Rebuild Container Without Cache** — fresh image layers, same volumes.
- **To force a re-login / clear an `EACCES`** — remove the per-container *config* volumes and rebuild. As of the session-volume change this **no longer drops your `--resume` history** (sessions are on separate volumes — see [Session resume](#session-resume-across-container-recreation)):
- **To force a re-login / clear an `EACCES`** — remove the per-container _config_ volumes and rebuild. As of the session-volume change this **no longer drops your `--resume` history** (sessions are on separate volumes — see [Session resume](#session-resume-across-container-recreation)):
```bash
docker volume ls | grep -- -config- # the credential / identity volumes
docker volume rm claude-config-<id> codex-config-<id> cursor-config-<id>
```
⚠️ Since the shareable dirs are now seeded into the config volume (not bind-mounted), wiping `<cli>-config` **also discards any plugin/skill/agent/command you installed _inside_ the container** and re-seeds those dirs from the host on the next rebuild. That is the intended way to pull host-side config changes in, but if you have in-container-only plugins you want to keep, reinstall them after the rebuild (or install them on the host first so the re-seed brings them along).
- **To also wipe session history** (a true clean slate) — remove the session volumes too (`<name>` is your workspace folder name):
```bash
docker volume ls | grep -E -- '-(sessions|cursor-projects)-' # the group-6 volumes
@ -326,6 +331,10 @@ VS Code's Ports panel shows forwarded ports once their listener starts.
<name>-cursor-sessions-<id> <name>-cursor-projects-<id>
```
Then rebuild.
- **To re-seed claude-mem from the host** (the container's memory has diverged and you want the host's current store back) — remove the claude-mem volume and rebuild; `post-create.sh` copies the host store in again on the next create:
```bash
docker volume rm claude-mem-<id>
```
## Bumping CLI versions
@ -339,16 +348,16 @@ Bump the version pins in `.devcontainer/devcontainer.json` `build.args` and rebu
## Troubleshooting
| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `GitNexus devcontainer one-time Windows setup` banner from `initializeCommand` | First-time Windows-native Reopen-in-Container; `HOME` env var was missing | The script just ran `setx HOME "%USERPROFILE%"` for you. Close ALL VS Code windows (File → Exit) and reopen — see [Windows 11 setup](#windows-11-setup) |
| `bind source path does not exist: /.claude` (or similar) from Docker | Windows-native `HOME` env var is still missing even after one rebuild — `setx` may have failed or VS Code wasn't fully restarted | Run `setx HOME "%USERPROFILE%"` in a Windows shell manually, fully exit VS Code (check Task Manager that no `Code.exe` remains), reopen |
| `EACCES` / `EPERM` writing into `~/.claude`, `~/.codex`, or `~/.cursor` inside the container | Stale state from a previous container with a different effective UID | Move the affected dir aside and let the CLI rebuild it (`mv ~/.claude ~/.claude.bak` and log in again). Long-term: WSL2 setup, which doesn't hit this class of issue |
| `EPERM: operation not permitted, copyfile ... '.husky/_/h'` in `postCreateCommand` | Leftover `.husky/_/` from a previous container run on a Windows-side bind mount | `post-create.sh` already runs `rm -rf .husky/_` defensively. If you hit this on an older config, delete `.husky/_/` on the host and rebuild. Long-term: clone in WSL2 |
| Vite never hot-reloads | Repo cloned on Windows side, not WSL2 | Re-clone inside WSL2 |
| `gitnexus-web` can't reach the backend | `4747` was remapped or backend isn't running | Verify the Ports panel shows `4747` forwarded with no remap; start the backend with `cd gitnexus && npx gitnexus serve` |
| `npm install` fails on tree-sitter-swift / proto / dart | Native build toolchain missing | This shouldn't happen in the devcontainer — verify the apt layer installed `python3 make g++`. If iterating, set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` to skip the vendored grammars |
| Integration tests fail with `database busy` | LadybugDB single-writer constraint | Don't run host-side `gitnexus analyze` while the container is also analyzing the same repo; choose one writer |
| API key env vars not visible inside the container | They are intentionally not auto-propagated from the host (so an empty/stale host var can't silently break `*-login` for everyone else) | `export ANTHROPIC_API_KEY=...` / `OPENAI_API_KEY=...` / `CURSOR_API_KEY=...` inside the container shell, or carry it via your VS Code [dotfiles repo](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories) for persistence |
| `git commit` produces commits with empty author | `~/.gitconfig` is missing or empty on the host (VS Code's auto-copy had nothing to copy) | Set `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"` from the host shell, then rebuild the container |
| `gh: not logged in` inside the container | Not logged in on the host, or `~/.config/gh/` source path missing on the host | Run `gh auth login` **on the host** — the `~/.config/gh` mount is read-only, so an in-container login won't persist; the host auth flows into the container on next attach |
| Symptom | Likely cause | Fix |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GitNexus devcontainer one-time Windows setup` banner from `initializeCommand` | First-time Windows-native Reopen-in-Container; `HOME` env var was missing | The script just ran `setx HOME "%USERPROFILE%"` for you. Close ALL VS Code windows (File → Exit) and reopen — see [Windows 11 setup](#windows-11-setup) |
| `bind source path does not exist: /.claude` (or similar) from Docker | Windows-native `HOME` env var is still missing even after one rebuild — `setx` may have failed or VS Code wasn't fully restarted | Run `setx HOME "%USERPROFILE%"` in a Windows shell manually, fully exit VS Code (check Task Manager that no `Code.exe` remains), reopen |
| `EACCES` / `EPERM` writing into `~/.claude`, `~/.codex`, or `~/.cursor` inside the container | Stale state from a previous container with a different effective UID | Move the affected dir aside and let the CLI rebuild it (`mv ~/.claude ~/.claude.bak` and log in again). Long-term: WSL2 setup, which doesn't hit this class of issue |
| `EPERM: operation not permitted, copyfile ... '.husky/_/h'` in `postCreateCommand` | Leftover `.husky/_/` from a previous container run on a Windows-side bind mount | `post-create.sh` already runs `rm -rf .husky/_` defensively. If you hit this on an older config, delete `.husky/_/` on the host and rebuild. Long-term: clone in WSL2 |
| Vite never hot-reloads | Repo cloned on Windows side, not WSL2 | Re-clone inside WSL2 |
| `gitnexus-web` can't reach the backend | `4747` was remapped or backend isn't running | Verify the Ports panel shows `4747` forwarded with no remap; start the backend with `cd gitnexus && npx gitnexus serve` |
| `npm install` fails on tree-sitter-swift / proto / dart | Native build toolchain missing | This shouldn't happen in the devcontainer — verify the apt layer installed `python3 make g++`. If iterating, set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` to skip the vendored grammars |
| Integration tests fail with `database busy` | LadybugDB single-writer constraint | Don't run host-side `gitnexus analyze` while the container is also analyzing the same repo; choose one writer |
| API key env vars not visible inside the container | They are intentionally not auto-propagated from the host (so an empty/stale host var can't silently break `*-login` for everyone else) | `export ANTHROPIC_API_KEY=...` / `OPENAI_API_KEY=...` / `CURSOR_API_KEY=...` inside the container shell, or carry it via your VS Code [dotfiles repo](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories) for persistence |
| `git commit` produces commits with empty author | `~/.gitconfig` is missing or empty on the host (VS Code's auto-copy had nothing to copy) | Set `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"` from the host shell, then rebuild the container |
| `gh: not logged in` inside the container | Not logged in on the host, or `~/.config/gh/` source path missing on the host | Run `gh auth login` **on the host** — the `~/.config/gh` mount is read-only, so an in-container login won't persist; the host auth flows into the container on next attach |

172
.devcontainer/devcontainer.json
View file

@ -52,20 +52,19 @@
// Mount topology, by group:
//
// 1. AI CLI host config — this has TWO roles. (a) A read-only stage at
// /host/.<cli>. On container-create, `post-create.sh` COPIES credentials,
// identity, and single config files out of it. It is read-only so a
// container can't write the credential snapshot back to the host.
// (b) Direct read-write bind mounts of the shareable subfolders (Claude
// 1. AI CLI host config — a READ-ONLY stage at /host/.<cli>. On container-
// create, `post-create.sh` COPIES out of it: credentials, identity, and
// single config files (always), plus the shareable subfolders (Claude
// plugins/skills/agents/memory/commands; Codex plugins/prompts/memories/
// skills; Cursor plugins/rules/commands/agents/skills). These overlay the
// named volume at their sub-paths. These read-write binds go both ways.
// Install a plugin in the container and it lands on the host; add one on
// the host and the container sees it. This write-through is a deliberate
// trade-off. A compromised npm dependency CAN drop files into your host
// plugin/agent/skill folders, which the next host session then loads. See
// README § "Trust boundary, concretely". Credentials never live on this
// surface. They stay in the volume (role 2).
// skills; Cursor plugins/rules/commands/agents/skills) ONCE on first create.
// Everything copied lands in the per-container named volume (role 2). It is
// read-only so a container process can NEVER write back to the host — there
// is no read-write bind into the host's CLI config at all. This protects the
// host's on-disk setup: a compromised in-container dependency cannot drop a
// skill, agent, command, or plugin onto the host for the next host session
// to load. The cost is that host and container DIVERGE after the first
// create — host edits don't reach the container until you wipe the config
// volume and rebuild. See README § "Trust boundary, concretely".
//
// 2. AI CLI container config — one named volume per devcontainer. CODEX_HOME
// points here. CLAUDE_CONFIG_DIR is left unset on purpose, so it resolves
@ -108,8 +107,9 @@
// rebuild, a full delete-and-recreate, AND that wipe. They overlay the
// config volume at the session sub-paths (Docker precedence: more specific
// path wins). Container-private by design — transcripts can hold pasted
// secrets, so unlike the group-1 plugin/agent binds these add NO host
// write-through surface and leak no other projects' transcripts. They do
// secrets, and like the group-1 config (read-only stage, copy-once) these
// add NO host write-through surface and leak no other projects' transcripts.
// They do
// NOT survive `docker volume prune`, a `${devcontainerId}` change (moving
// the checkout, WSL vs native), or a new machine — same tier as group 5.
// To make sessions host-visible/portable instead, see the commented
@ -126,9 +126,26 @@
"source=codex-config-${devcontainerId},target=/home/node/.codex,type=volume",
"source=cursor-config-${devcontainerId},target=/home/node/.cursor,type=volume",
// claude-mem store. UNLIKE the shareable dirs below (skills/agents/memory),
// this is NOT a host bind. $HOME/.claude-mem is a large, multi-GB SQLite +
// Chroma vector store (claude-mem.db + -wal/-shm, chroma/chroma.sqlite3, HNSW
// index binaries). A read-write host bind would (a) push every byte over the
// 9p/virtiofs share, and (b) expose those SQLite WAL files to unreliable
// fcntl locking across that boundary — with a real corruption risk if
// claude-mem ran on the host and in the container against the same DB at
// once. So it gets its OWN per-container named volume here, same durability
// tier as the config volumes (survives Rebuild Container and a
// delete-and-recreate; keyed by ${devcontainerId}). post-create.sh SEEDS it
// ONCE from the /host/.claude-mem read-only stage when the volume is empty,
// then the container owns its copy — rebuilds never clobber it, and changes
// do NOT flow back to the host. (Container and host memory diverge from the
// seed point on; that is the price of safe SQLite.) Removed by the same
// `docker volume rm` reset flow as the other volumes — see README.
"source=claude-mem-${devcontainerId},target=/home/node/.claude-mem,type=volume",
// Per-workspace SESSION volumes (mount group 6). These OVERLAY the config
// volumes above at the session sub-paths so "resume my last session"
// survives container recreation the way the host-bound plugin dirs do.
// survives container recreation the way the seeded config dirs do.
// They are SEPARATE volumes from <cli>-config-${devcontainerId}, so the
// README's `docker volume rm <cli>-config-${devcontainerId}` re-login fix
// does not touch them. post-create.sh chowns each one explicitly (its
@ -178,88 +195,49 @@
// "source=${localEnv:HOME}/.cursor/chats,target=/home/node/.cursor/chats,type=bind",
// "source=${localEnv:HOME}/.cursor/projects,target=/home/node/.cursor/projects,type=bind",
// Read-only host stage that post-create.sh copies credentials and
// identity from on container-create. It is read-only so a container
// process can't write back to host CLI state files. That write-back is the
// attack vector we are blocking. Only the credential and identity files
// are READ here. Shareable content is bind-mounted directly read-write
// below, not staged here.
// Read-only host stage that post-create.sh copies FROM on container-create.
// It is read-only so a container process can never write back to host CLI
// state — that write-back is the attack vector we block. post-create.sh
// reads two kinds of thing from here: (a) the credential + identity files
// (copied into the volume always), and (b) the shareable dirs — skills,
// agents, plugins, memory, commands, prompts, rules — which it copies into
// the volume ONCE on first create (see step 3/4). Nothing here is bound
// read-write into the container, so the host's on-disk setup is protected.
"source=${localEnv:HOME}/.claude,target=/host/.claude,type=bind,readonly",
"source=${localEnv:HOME}/.codex,target=/host/.codex,type=bind,readonly",
"source=${localEnv:HOME}/.cursor,target=/host/.cursor,type=bind,readonly",
// Read-only host stage for the claude-mem store. post-create.sh COPIES it
// into the claude-mem named volume on first create (seed-once). Read-only so
// the container can never write back to the host's live DB — the seed is a
// one-way snapshot. ensure-host-config-dirs.cjs creates ~/.claude-mem on the
// host so this bind resolves even when claude-mem was never installed there.
"source=${localEnv:HOME}/.claude-mem,target=/host/.claude-mem,type=bind,readonly",
// Direct read-write bind mounts for shareable subfolders and files. These
// OVERLAY the named volume at their target paths, so reads and writes
// inside the container go straight to the host. `/plugin marketplace add`
// in the container means it is installed on the host. A new skill on the
// host shows up in the container on the next read. We accept the trade-off:
// a compromised npm dependency can write into host plugin, skill, agent,
// memory, and command folders.
// Plugins are split in two. The SOURCE (the marketplaces/ git clones and
// the cache/ of extracted plugin files) does not depend on absolute paths,
// so it is bind-mounted both ways. The REGISTRY (known_marketplaces.json,
// installed_plugins.json, plugin-catalog-cache.json) holds absolute,
// OS-specific paths (`C:\Users\X\.claude\plugins\...` on Windows,
// `/Users/x/...` on macOS), so it CANNOT be shared as-is. It stays in the
// named volume. post-create.sh generates it from the host's versions, with
// the paths rewritten to the container's Linux paths.
// These are DIRECTORY binds, so they work both ways. Atomic writes inside
// a directory work fine, because the temp file and the target are on the
// same filesystem. Writes under these paths in the container reach the host
// right away, and host changes are visible to the container right away.
//
// Claude: the plugin SOURCE folders (the marketplaces/ git clones and the
// cache/ of extracted files) do not depend on absolute paths. The registry
// JSON files at the plugins/ root DO carry paths, so they stay in the
// volume, and post-create.sh rewrites their paths. See the SINGLE-FILE note
// below.
"source=${localEnv:HOME}/.claude/plugins/marketplaces,target=/home/node/.claude/plugins/marketplaces,type=bind",
"source=${localEnv:HOME}/.claude/plugins/cache,target=/home/node/.claude/plugins/cache,type=bind",
"source=${localEnv:HOME}/.claude/skills,target=/home/node/.claude/skills,type=bind",
"source=${localEnv:HOME}/.claude/agents,target=/home/node/.claude/agents,type=bind",
"source=${localEnv:HOME}/.claude/memory,target=/home/node/.claude/memory,type=bind",
"source=${localEnv:HOME}/.claude/commands,target=/home/node/.claude/commands,type=bind",
//
// Codex: bind the WHOLE plugins/ folder (the parent of cache/). `codex
// plugin add` stages installs INSIDE plugins/cache/<marketplace>/ and
// renames within that folder (confirmed with strace). So under a single
// bind of plugins/, the rename stays on the same filesystem and never hits
// the EXDEV cross-filesystem error. Unlike Claude, Codex has NO path-
// bearing registry file under plugins/. Enablement lives in config.toml at
// the .codex root, as git URLs, not filesystem paths. So nothing needs
// rewriting and the whole folder can be bound. `.tmp/` is the ext4 staging
// area for marketplace clones, and it is deliberately NOT bound. It must
// stay on the volume as the source side of the cross-filesystem copy.
"source=${localEnv:HOME}/.codex/plugins,target=/home/node/.codex/plugins,type=bind",
"source=${localEnv:HOME}/.codex/prompts,target=/home/node/.codex/prompts,type=bind",
"source=${localEnv:HOME}/.codex/memories,target=/home/node/.codex/memories,type=bind",
"source=${localEnv:HOME}/.codex/skills,target=/home/node/.codex/skills,type=bind",
//
// Cursor: cursor-agent (the CLI, not just the IDE) shares the Cursor 2.5
// plugin/rules/commands/agents/skills files on disk. Bind the SOURCE
// folders, which don't depend on absolute paths.
// plugins/installed_plugins.json carries absolute Windows paths, like
// Claude's registry, so it stays in the volume and post-create.sh rewrites
// it. That is why the plugins/ sub-folders are bound one by one instead of
// binding the whole plugins/ folder. mcp.json and hooks.json are single
// files, which are unsafe to bind (the EXDEV error), so they are copied on
// create instead. hooks.json is also NOT synced at all. Cursor hooks run
// shell commands on a timer or event, with no user action, so a poisoned
// host hooks.json would run by itself in the container. NOTE this is a
// partial fix, not a clean boundary. The read-write bound
// commands/agents/skills/rules folders (here and for Claude) are also
// surfaces that hold instructions or run shell commands, and a compromised
// dependency can write through them to the host. Skipping hooks.json just
// removes the one surface that fires WITHOUT an agent choosing to run it.
// The wider write-through trade-off is accepted and documented in README
// § Trust boundary. To fully close it, switch these folders to copy-on-
// create too.
"source=${localEnv:HOME}/.cursor/plugins/marketplaces,target=/home/node/.cursor/plugins/marketplaces,type=bind",
"source=${localEnv:HOME}/.cursor/plugins/local,target=/home/node/.cursor/plugins/local,type=bind",
"source=${localEnv:HOME}/.cursor/rules,target=/home/node/.cursor/rules,type=bind",
"source=${localEnv:HOME}/.cursor/commands,target=/home/node/.cursor/commands,type=bind",
"source=${localEnv:HOME}/.cursor/agents,target=/home/node/.cursor/agents,type=bind",
"source=${localEnv:HOME}/.cursor/skills,target=/home/node/.cursor/skills,type=bind",
// NO read-write bind mounts for the shareable subfolders. They USED to be
// bound here (Claude skills/agents/memory/commands/plugins; Codex plugins/
// prompts/memories/skills; Cursor rules/commands/agents/skills/plugins) so
// host and container shared one copy both ways. That bind was a write-through
// hole: a compromised in-container dependency could drop a malicious skill,
// agent, command, or plugin straight onto the host, which the next HOST
// session would auto-load. To protect the host's on-disk setup, these are
// now COPIED once from the read-only /host/.<cli> stage into the per-container
// named volume by post-create.sh (step 3/4), exactly like claude-mem and the
// session volumes. Trade-offs of the copy model:
// - The container gets its OWN writable copy and can never write back to
// the host. Host setup is protected.
// - It is seed-ONCE: host edits made after first create don't reach the
// container until you remove the config volume and rebuild. Container
// edits persist across rebuilds. (See README § Rebuild/reset to re-seed.)
// - The plugin REGISTRY JSONs (Claude known_marketplaces.json /
// installed_plugins.json / plugin-catalog-cache.json; Cursor
// installed_plugins.json) carry absolute OS-native paths, so they can't
// be copied verbatim — post-create.sh translates their paths to the
// container's Linux paths, also seed-once, alongside the cache/ copy so
// the two stay consistent. Codex needs no translation (config.toml holds
// git URLs, not paths), so its whole plugins/ dir is copied as-is.
// - The old read-only-stage-plus-symlink design failed `/plugin marketplace
// add` in the container with EROFS; copy-into-a-writable-volume avoids
// that — the container writes to its own copy, not a read-only mount.
//
// SINGLE-FILE binds for settings.json, .claude.json, and config.toml are
// deliberately ABSENT. On Docker Desktop Windows the named volume sits on
@ -301,9 +279,9 @@
// codex-config, cursor-config), NOT in the host bind mounts. They are copied
// from the read-only /host/.<cli> stage into the volume on container-create.
// Single-file binds would break on Docker Desktop Windows (the EXDEV error).
// Only shareable content (plugins, skills, agents, memory, commands) is
// bound read-write to the host ~/.claude, ~/.codex, and ~/.cursor folders
// declared in the mounts block above.
// Shareable content (plugins, skills, agents, memory, commands) is NOT bound
// read-write — it is copied once from the read-only /host/.<cli> stage into
// the volume on first create, so the host's on-disk setup stays protected.
// API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, CURSOR_API_KEY) are NOT
// injected via containerEnv. `${localEnv:VAR}` turns an unset host var into
// an empty string. Cursor in particular treats `CURSOR_API_KEY=""` as "use

59
.devcontainer/ensure-host-config-dirs.cjs
View file

@ -26,46 +26,33 @@ const fs = require('fs');
const os = require('os');
const path = require('path');
// Folders that are bind-mount sources. devcontainer.json declares read-write
// binds for the shareable subfolders (plugins/skills/agents/memory/commands for
// Claude; memories/skills for Codex) so reads and writes pass straight between
// host and container. Docker rejects a bind mount whose source is missing, so
// we create each one. We also create the top per-CLI folders themselves
// (~/.claude, ~/.codex, ~/.cursor). Those back the /host/.<cli> read-only stage
// mounts that post-create.sh reads credentials from.
// Folders that are bind-mount sources in devcontainer.json. Docker rejects a
// bind mount whose source is missing, so we create each one.
//
// We create the TOP per-CLI folders (~/.claude, ~/.codex, ~/.cursor) and
// ~/.claude-mem. These back the /host/.<cli> and /host/.claude-mem read-only
// STAGE mounts that post-create.sh copies from on container-create. We do NOT
// create the shareable subfolders (skills/agents/plugins/memory/commands/...)
// here anymore: they used to be read-write bind sources, but they are now
// copied once out of the read-only stage into the per-container volume, so they
// are no longer bind sources and pre-creating empty ones would needlessly write
// into the host of someone who never used that CLI. post-create.sh's seed step
// simply skips any subfolder the host doesn't have. The read-only stage bind is
// the whole ~/.<cli> dir, so whatever shareable subfolders DO exist are visible
// to the seed without being listed here.
const DIRS = [
'.claude',
path.join('.claude', 'plugins'),
// Claude plugin source folders. Their content does not depend on absolute
// paths, so they get a two-way read-write bind mount. The registry JSON files
// that DO contain paths (known_marketplaces.json, installed_plugins.json,
// plugin-catalog-cache.json) stay in the container's named volume instead,
// where post-create.sh rewrites their paths.
path.join('.claude', 'plugins', 'marketplaces'),
path.join('.claude', 'plugins', 'cache'),
path.join('.claude', 'skills'),
path.join('.claude', 'agents'),
path.join('.claude', 'memory'),
path.join('.claude', 'commands'),
// Codex shareable folders. The whole plugins/ folder is bound, because it has
// no path-bearing registry inside it (enablement lives in config.toml at the
// root). Plus prompts/ (the saved prompt library), memories/, and skills/.
// claude-mem store ($HOME/.claude-mem). A SEPARATE top-level folder from
// ~/.claude, holding claude-mem's SQLite DB + Chroma vector store. It is NOT
// bind-mounted (a multi-GB SQLite/WAL store is unsafe over a 9p bind on Docker
// Desktop Windows). post-create.sh SEEDS it once into a per-container named
// volume from the /host/.claude-mem read-only stage. We create the source here
// so that stage bind resolves even for a host that never ran claude-mem
// (Docker rejects a missing bind source); the seed then finds no DB to copy
// and the container starts with empty memory.
'.claude-mem',
'.codex',
path.join('.codex', 'plugins'),
path.join('.codex', 'prompts'),
path.join('.codex', 'memories'),
path.join('.codex', 'skills'),
// Cursor shareable folders. The cursor-agent CLI shares the Cursor 2.5
// plugin/rules/commands/agents/skills folders. The plugins/ subfolders are
// bound one by one. That is because plugins/installed_plugins.json holds
// absolute paths, so post-create.sh rewrites it instead of binding it.
'.cursor',
path.join('.cursor', 'plugins', 'marketplaces'),
path.join('.cursor', 'plugins', 'local'),
path.join('.cursor', 'rules'),
path.join('.cursor', 'commands'),
path.join('.cursor', 'agents'),
path.join('.cursor', 'skills'),
'.ssh',
'.docker',
'.aws',

199
.devcontainer/post-create.sh
View file

@ -10,7 +10,7 @@ set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
echo "[post-create] 1/2: chown AI CLI named-volume mount points"
echo "[post-create] 1/4: chown AI CLI named-volume mount points"
# Fix ownership on the named volumes (~/.claude, ~/.codex, ~/.cursor,
# /commandhistory). When they first mount, they take the user ID baked into the
# image, before any realignment. Then `updateRemoteUserUID: true` shifts the
@ -20,26 +20,25 @@ echo "[post-create] 1/2: chown AI CLI named-volume mount points"
# This script fixes the AI CLI side, so each lifecycle hook handles its own part.
#
# There are two separate guards here, and they do different things. `-xdev`
# keeps find from descending into other filesystems. It stops at the volume's
# own filesystem and won't walk into the read-write host bind mounts layered at
# sub-paths (plugins/marketplaces, plugins/cache, skills, agents, memory,
# commands, codex/plugins, cursor/*). Those bind mounts live on a DIFFERENT
# filesystem (9p, virtiofs, or bind). Walking into them would rewrite the
# ownership of the host's own files on a Linux host whose user IDs don't line
# up. Worse, a permission error there would kill provisioning before
# credentials ever sync. `-h` tells chown to act on a symlink ITSELF instead of
# following it. So it never lands on a target across a filesystem boundary, and
# it never aborts on a broken symlink under `set -e`. For regular files and
# directories `-h` does nothing extra.
# keeps find from descending into other filesystems. The shareable dirs (skills,
# agents, plugins, memory, commands, prompts, rules) are no longer host bind
# mounts — they now live INSIDE the config volume (seeded in step 3/4), so
# `-xdev` correctly walks and chowns them as the container-private volume files
# they are. What `-xdev` still stops at are the SESSION volumes (mount group 6),
# which remain separate filesystems mounted at sub-paths (see below). `-h` tells
# chown to act on a symlink ITSELF instead of following it, so it never lands on
# a target across a filesystem boundary and never aborts on a broken symlink
# under `set -e` (a legacy Option-B symlink could still exist on a carried-over
# volume). For regular files and directories `-h` does nothing extra.
#
# The session volumes (mount group 6: .claude/projects, .codex/sessions,
# .cursor/chats, .cursor/projects) are their OWN filesystems mounted at
# sub-paths, so `-xdev` rooted at the config-volume parent deliberately skips
# them. That is why each one is listed as its own root below: rooted there,
# `-xdev` walks just that volume and chowns its top level, so the CLI's first
# write doesn't hit EACCES on a stale image UID. We DO chown these (unlike the
# host bind mounts) precisely because they are container-private volumes, not
# the host's own files.
# write doesn't hit EACCES on a stale image UID. These are container-private
# volumes, not the host's own files — the read-only /host/.<cli> stages we copy
# from are mounted elsewhere and are never chowned.
DIRS=(
/home/node/.claude
/home/node/.claude/projects
@ -51,6 +50,14 @@ DIRS=(
/home/node/.local
/commandhistory
)
# claude-mem volume: chown it ONLY on first create (its completion sentinel is
# absent). The step-4/4 seed copies the store as the node user, so a populated
# claude-mem volume is already node-owned on every later rebuild — a recursive
# `find` over a multi-GB store (the 7GB+ DB plus the Chroma index) just to
# re-stamp ownership that is already correct would add real latency to every
# rebuild for nothing. On first create the volume is empty, so this chown of the
# bare mount point is trivial and lets the seed write into it.
[ -f /home/node/.claude-mem/.claude-mem-seeded ] || DIRS+=(/home/node/.claude-mem)
for d in "${DIRS[@]}"; do
# Skip a root that isn't present rather than aborting the whole run under
# `set -e`. Docker creates every declared volume's mount point before this
@ -62,15 +69,13 @@ for d in "${DIRS[@]}"; do
sudo find "$d" -xdev -exec chown -h node:node {} +
done
echo "[post-create] 2/2: sync AI CLI credentials + identity from host"
echo "[post-create] 2/4: sync AI CLI credentials + identity from host"
# Clean up after an older devcontainer design (Option B). Back then these paths
# were symlinks pointing into the read-only host stage
# (e.g. /home/node/.claude/plugins -> /host/.claude/plugins). The current setup
# bind-mounts sub-paths read-write, but it does not replace the parent symlink
# itself. So a write to, say, /home/node/.claude/plugins/known_marketplaces.json
# would follow the old symlink to a read-only host file and fail with a
# read-only-filesystem error. Delete those symlinks here. The mkdir -p below
# then recreates them as real directories in the named volume.
# (e.g. /home/node/.claude/plugins -> /host/.claude/plugins). A write through
# such a symlink would land on a read-only host file and fail. Delete any that
# survive on a carried-over volume. The shareable dirs are now real directories
# in the named volume, seeded from the host in step 3/4 below.
for p in plugins skills agents memory commands; do
[ -L "/home/node/.claude/$p" ] && rm "/home/node/.claude/$p"
done
@ -82,14 +87,12 @@ for p in plugins rules commands agents skills; do
done
mkdir -p /home/node/.claude/plugins /home/node/.cursor/plugins
# Shareable content is bind-mounted read-write straight from the host in
# devcontainer.json. Changes flow both ways, so this script does nothing for it:
# - Claude: plugins/{marketplaces,cache}, skills, agents, memory, commands
# - Codex: plugins (whole dir), prompts, memories, skills
# - Cursor: plugins/{marketplaces,local}, rules, commands, agents, skills
#
# The rest stays per-container, in the named volume, and is COPIED from the host
# once when the container is created:
# Shareable content (skills, agents, plugins, memory, commands, prompts, rules)
# is NO LONGER bind-mounted. It is COPIED once from the read-only host stage into
# the named volume in step 3/4 below, so a compromised in-container dependency
# can't write through to the host's on-disk CLI setup. This step handles only the
# credentials, identity, and single config files. Those stay per-container in the
# named volume and are COPIED from the host once when the container is created:
# - .credentials.json (Claude OAuth tokens)
# - .claude/.claude.json (Claude identity: userID, oauthAccount, and
# migration tracking — a different file from $HOME/.claude.json)
@ -148,18 +151,6 @@ sync_from_host /host/.codex/config.toml /home/node/.codex/config.toml 644
# (translate-plugin-registries.test.cjs).
node "$SCRIPT_DIR/seed-claude-config.cjs"
# Translate the plugin registry paths (Claude + Cursor). Both write absolute,
# OS-native install paths into their plugin registry JSONs —
# `C:\Users\X\.claude\plugins\...` on Windows, `/Users/X/.cursor/plugins/...`
# on macOS. That means the host versions can't be bind-mounted into the Linux
# container, because the CLI can't resolve a Windows path under Linux and fails
# with `cache-miss`. The translation rewrites those paths. It uses a regex, a
# deep rewrite, and the REGISTRIES table, all in translate-plugin-registries.cjs
# so it can be unit-tested and prettier-checked. Codex needs no translation. Its
# enablement registry is config.toml, and that holds git URLs rather than
# filesystem paths, so its whole plugins/ dir is bind-mounted instead.
node "$SCRIPT_DIR/translate-plugin-registries.cjs"
# Codex auth. Some hosts store credentials in the OS keyring instead of on disk
# (`cli_auth_credentials_store = "keyring"`, the default on macOS). Those hosts
# have no auth.json file, so the copy below quietly does nothing. In that case,
@ -181,4 +172,128 @@ sync_from_host \
sync_from_host \
/host/.cursor/mcp.json /home/node/.cursor/mcp.json 644
echo "[post-create] 3/4: seed shareable config dirs from host (first create only)"
# The shareable dirs (Claude skills/agents/memory/commands/plugins; Codex
# plugins/prompts/memories/skills; Cursor rules/commands/agents/skills/plugins)
# used to be read-write host bind mounts, so a write inside the container landed
# directly on the host's files. That exposed the host's on-disk CLI setup: a
# compromised workspace dependency running in the container could drop a malicious
# skill, agent, command, or plugin into the host's folders, which the next HOST
# session would then auto-load. To protect the host, these are no longer bound.
# Instead we COPY them once from the read-only /host/.<cli> stage into the
# per-container named volume, exactly like claude-mem (step 4/4) and the session
# volumes. The container gets its own writable copy and can NEVER write back to
# the host. The container also avoids the old read-only-stage EROFS failure,
# because it writes to its own volume copy, not a read-only mount.
#
# Seed-once, persist: a per-CLI marker file records that the copy has happened.
# On the first container-create the marker is absent, so we copy; on every later
# rebuild the marker is present, so we skip and keep whatever the container has
# accumulated. Host edits made AFTER the first create do NOT reach the container
# until you remove the config volume and rebuild (see README § Rebuild/reset).
seed_shareable() {
# seed_shareable <cli> <subdir>...: copy each /host/.<cli>/<subdir> into the
# named volume, once. Skips a subdir the host doesn't have. We use `cp -r`,
# NOT `cp -a`/`cp -p`: this script runs as the non-root node user, and the
# host-stage files are owned by a different UID, so trying to preserve
# ownership would fail with EPERM and abort the run under `set -e` (the same
# reason sync_from_host uses plain cp). `cp -r` copies contents owned by node
# — exactly what we want — and preserves symlinks as symlinks (GNU default).
local cli=$1
shift
local marker="/home/node/.$cli/.devcontainer-shareable-seeded"
[ -f "$marker" ] && return 0
for sub in "$@"; do
local src="/host/.$cli/$sub"
local dst="/home/node/.$cli/$sub"
[ -d "$src" ] || continue
mkdir -p "$dst"
cp -r "$src/." "$dst/"
done
}
# Decide which plugin registries to translate BEFORE seeding sets the markers.
# We translate only a CLI being seeded this run, so a plugin installed inside the
# container isn't overwritten by the host's registry on a later rebuild. Codex
# has no path-bearing registry (config.toml holds git URLs), so it's never here.
TRANSLATE_CLIS=()
[ -f /home/node/.claude/.devcontainer-shareable-seeded ] || TRANSLATE_CLIS+=(claude)
[ -f /home/node/.cursor/.devcontainer-shareable-seeded ] || TRANSLATE_CLIS+=(cursor)
seed_shareable claude skills agents memory commands plugins/marketplaces plugins/cache
seed_shareable codex plugins prompts memories skills
seed_shareable cursor rules commands agents skills plugins/marketplaces plugins/local
# Translate the path-bearing plugin registries (Claude + Cursor) for the CLIs we
# just seeded. They store absolute, OS-native install paths
# (`C:\Users\X\.claude\plugins\...` on Windows), which the Linux container can't
# resolve — it would fail with `cache-miss`. translate-plugin-registries.cjs
# rewrites those to the container's paths and writes the result into the volume.
if [ "${#TRANSLATE_CLIS[@]}" -gt 0 ]; then
node "$SCRIPT_DIR/translate-plugin-registries.cjs" "${TRANSLATE_CLIS[@]}"
fi
# Record that each CLI's shareable surface is seeded, so later rebuilds keep the
# container's copy. Touch even when the host had nothing to copy — an empty CLI
# is still "seeded", and we don't want to re-scan the host on every rebuild.
#
# ORDERING INVARIANT — do NOT move these touches earlier (e.g. into
# seed_shareable per-CLI). The markers must be written only AFTER the registry
# translation above, because seed (cache copy) and translate (registry rewrite)
# are logically atomic: a marker set between them would let a later rebuild skip
# translation for an already-seeded CLI, leaving its cache/ in place but its
# registry still pointing at host paths (`cache-miss`). Writing all markers here,
# after translate, means any abort mid-seed leaves NO markers, so the next create
# re-runs the whole seed+translate. The cost is re-copying an already-copied CLI
# on retry; `cp -r` overwrites in place, so that is idempotent and cheap relative
# to a broken plugin registry.
for cli in claude codex cursor; do
touch "/home/node/.$cli/.devcontainer-shareable-seeded"
done
echo "[post-create] 4/4: seed claude-mem store from host (first create only)"
# claude-mem keeps its memory in $HOME/.claude-mem — a SQLite DB (claude-mem.db
# plus -wal/-shm) and a Chroma vector store (chroma/chroma.sqlite3 + HNSW index
# binaries). It is mounted as a per-container named volume, NOT a host bind:
# pushing a multi-GB SQLite/WAL store over the 9p/virtiofs bind risks unreliable
# fcntl locking and corruption, especially if claude-mem ran on the host and in
# the container against the same files at once (see devcontainer.json).
#
# So seed it ONCE, then let the container own its copy. On every later rebuild
# we skip the copy and keep whatever the container has accumulated since —
# rebuilds never clobber it. The container's memory and the host's diverge from
# this seed point on; that is the deliberate cost of keeping SQLite off a shared
# bind. To re-seed from the host, remove the volume (`docker volume rm
# claude-mem-<id>`) and rebuild.
#
# The skip guard is a COMPLETION SENTINEL (.claude-mem-seeded), NOT the presence
# of claude-mem.db. Keying on the DB file would be a trap: a multi-GB `cp -r` can
# be interrupted (disk full, I/O error) and abort the script under `set -e`,
# leaving a PARTIAL claude-mem.db behind. The next create would then see that
# truncated file and treat the store as "already seeded", sticking the container
# with a corrupt DB forever. With a sentinel touched only AFTER `cp` returns 0,
# an interrupted seed leaves no sentinel; the next create clears the half-copied
# store and retries cleanly. CONSISTENCY: copying a live WAL database is only
# crash-consistent if claude-mem is NOT writing on the host during the copy — do
# not run claude-mem on the host during a first-create or a re-seed rebuild.
#
# `cp -r` (not `cp -a`/`cp -p`) copies the DB together with its -wal/-shm
# sidecars in one pass. We avoid preserving ownership for the same reason as the
# shareable seed above: this runs as the non-root node user against host-owned
# files, so `cp -a` would fail with EPERM and abort under `set -e`. `cp -r`
# leaves the copies owned by node. The host stage is read-only, so this can
# never write back to the host's live DB.
if [ -f /host/.claude-mem/claude-mem.db ] && [ ! -f /home/node/.claude-mem/.claude-mem-seeded ]; then
echo "[post-create] seeding ~/.claude-mem from host (one-time copy, may be several GB)"
# Clear any partial store left by a previously-interrupted seed (mindepth 1
# so the volume mount point itself is never removed), then copy and only then
# write the sentinel. A partial store is node-owned (cp runs as node, and
# step 1 re-chowns the volume whenever the sentinel is absent), so no sudo.
find /home/node/.claude-mem -mindepth 1 -maxdepth 1 -exec rm -rf {} +
cp -r /host/.claude-mem/. /home/node/.claude-mem/
touch /home/node/.claude-mem/.claude-mem-seeded
else
echo "[post-create] skipping claude-mem seed (already seeded, or host has no store)"
fi
echo "[post-create] done"

15
.devcontainer/translate-plugin-registries.cjs
View file

@ -12,7 +12,7 @@
//
// Codex is left alone. Its registry is config.toml and holds git URLs, not
// filesystem paths, so there's nothing to translate — its whole plugins/ dir is
// bind-mounted instead.
// copied as-is into the container volume instead (seeded once by post-create.sh).
//
// This code lived inside a post-create.sh heredoc. We pulled it out so the regex
// and the deep rewrite can be unit-tested and prettier-checked. The regex has
@ -91,8 +91,17 @@ function translate(registries) {
}
}
module.exports = { buildRe, rewriteDeep, REGISTRIES, translate };
// Filter the registry table by CLI name. post-create.sh passes the CLIs it is
// seeding this run (e.g. `claude`), so a registry is only (re)generated on the
// FIRST container-create for that CLI — never on a rebuild, where it would
// clobber a plugin the user installed inside the container. An empty filter
// (no args) means "translate every registry" — the original behavior.
function selectRegistries(registries, only) {
return only && only.length ? registries.filter((r) => only.includes(r.cli)) : registries;
}
module.exports = { buildRe, rewriteDeep, REGISTRIES, translate, selectRegistries };
if (require.main === module) {
translate(REGISTRIES);
translate(selectRegistries(REGISTRIES, process.argv.slice(2)));
}

68
.devcontainer/translate-plugin-registries.test.cjs
View file

@ -27,7 +27,12 @@ const fs = require('node:fs');
const path = require('node:path');
const { execFileSync } = require('node:child_process');
const { buildRe, rewriteDeep, translate } = require('./translate-plugin-registries.cjs');
const {
buildRe,
rewriteDeep,
translate,
selectRegistries,
} = require('./translate-plugin-registries.cjs');
const { sanitizeClaudeConfig, readHostConfig } = require('./seed-claude-config.cjs');
const { ensurePaths, DIRS, FILES } = require('./ensure-host-config-dirs.cjs');
@ -266,6 +271,31 @@ test('translate: empty and missing host registries are skipped without error', (
}
});
// --- selectRegistries: the per-CLI filter post-create.sh drives translate with
test('selectRegistries: no filter -> all registries (original behavior)', () => {
const regs = [{ cli: 'claude' }, { cli: 'cursor' }];
assert.deepEqual(selectRegistries(regs, []), regs);
assert.deepEqual(selectRegistries(regs, undefined), regs);
});
test('selectRegistries: filter keeps only the named CLIs', () => {
const regs = [{ cli: 'claude' }, { cli: 'cursor' }];
assert.deepEqual(selectRegistries(regs, ['claude']), [{ cli: 'claude' }]);
assert.deepEqual(selectRegistries(regs, ['cursor']), [{ cli: 'cursor' }]);
assert.deepEqual(selectRegistries(regs, ['claude', 'cursor']), regs);
});
test('selectRegistries: an unknown CLI name selects nothing', () => {
const regs = [{ cli: 'claude' }, { cli: 'cursor' }];
assert.deepEqual(selectRegistries(regs, ['codex']), []);
});
test('selectRegistries: empty registry table stays empty under any filter', () => {
assert.deepEqual(selectRegistries([], ['claude']), []);
assert.deepEqual(selectRegistries([], []), []);
});
// --- seed-claude-config main(): end-to-end, through the real CLI entry point
const SEED_SCRIPT = path.join(__dirname, 'seed-claude-config.cjs');
@ -368,3 +398,39 @@ test('ensurePaths: does NOT pre-create settings.json / config.toml (no gratuitou
fs.rmSync(home, { recursive: true, force: true });
}
});
test('ensurePaths: does NOT pre-create the shareable subdirs (now copied, not bound)', () => {
// The shareable dirs are seeded into the per-container volume from the
// read-only /host stage, so they are no longer bind-mount sources. Pre-creating
// empty ones would needlessly write into the host of someone who never used a
// CLI. This pins the DIRS trim: re-adding any of these would fail the test.
const home = tmp();
const mustNotExist = [
path.join('.claude', 'skills'),
path.join('.claude', 'agents'),
path.join('.claude', 'memory'),
path.join('.claude', 'commands'),
path.join('.claude', 'plugins'),
path.join('.codex', 'plugins'),
path.join('.codex', 'prompts'),
path.join('.codex', 'memories'),
path.join('.codex', 'skills'),
path.join('.cursor', 'rules'),
path.join('.cursor', 'commands'),
path.join('.cursor', 'agents'),
path.join('.cursor', 'skills'),
path.join('.cursor', 'plugins'),
];
try {
ensurePaths(home);
for (const sub of mustNotExist) {
assert.equal(fs.existsSync(path.join(home, sub)), false, `should not pre-create: ${sub}`);
}
// The top-level stage roots that ARE still bind sources must exist.
for (const top of ['.claude', '.codex', '.cursor', '.claude-mem']) {
assert.equal(fs.statSync(path.join(home, top)).isDirectory(), true, `missing root: ${top}`);
}
} finally {
fs.rmSync(home, { recursive: true, force: true });
}
});