mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-09-29 01:41:42 +00:00
d2047844f4
The devcontainer comments had grown dense and jargon-heavy. Rewrite them across all 9 files into short, plain-English sentences — same facts and reasoning, just clearer wording. Comments only; no code changed. Verified: the diff touches comment lines only, 25/25 config-transform tests pass, devcontainer.json is still valid JSONC with build.args + readonly mounts unchanged, shell scripts pass `bash -n`, and prettier is clean.
330 lines
20 KiB
JSON
330 lines
20 KiB
JSON
// Devcontainer for GitNexus. It pre-installs Claude Code, the OpenAI Codex
|
|
// CLI, and the Cursor CLI, plus the Node.js native build chain. It works on
|
|
// macOS, Linux, Windows via WSL2, and Windows native. Windows native needs a
|
|
// one-time HOME setup. That setup runs automatically via initializeCommand.
|
|
// See .devcontainer/README.md § Windows 11 setup. Open it with the VS Code
|
|
// Dev Containers extension.
|
|
//
|
|
// For first-time setup, auth flows, and troubleshooting, see
|
|
// .devcontainer/README.md.
|
|
{
|
|
"name": "GitNexus AI CLI Devcontainer",
|
|
|
|
"build": {
|
|
"dockerfile": "Dockerfile",
|
|
"context": ".",
|
|
"args": {
|
|
"CLAUDE_CODE_VERSION": "2.1.153",
|
|
"CODEX_VERSION": "0.134.0",
|
|
// Cursor: a pinned version plus one sha256 hash per CPU arch. The
|
|
// Dockerfile checks the tarball against the hash at build time, so it
|
|
// never runs a remote install script. Bump all three values together.
|
|
// Re-hash each arch with:
|
|
// curl -fSL https://downloads.cursor.com/lab/<ver>/linux/<x64|arm64>/agent-cli-package.tar.gz | sha256sum
|
|
"CURSOR_VERSION": "2026.05.28-a70ca7c",
|
|
"CURSOR_SHA256_X64": "7f8b6a09393e0b84b288cc6952b292fc98d15775f644cc01b0b9aa4f04b268df",
|
|
"CURSOR_SHA256_ARM64": "05a0ab361e038729aba25fe7f407531b3e8432912e499d0bffdf1dda0e7833e9",
|
|
"TZ": "${localEnv:TZ:UTC}"
|
|
}
|
|
},
|
|
|
|
// Runs on the HOST, not the container, before the container is created. We
|
|
// write it as a single string on purpose. The spec treats the single-string
|
|
// form as one command that each OS runs its own way. The object form means
|
|
// "named parallel tasks", not per-OS dispatch. We run it with Node so the
|
|
// same command works in cmd.exe on Windows and in bash/zsh on Linux, macOS,
|
|
// and WSL. The script reads `os.homedir()`, which respects $HOME on
|
|
// Linux/macOS and %USERPROFILE% on Windows. It then creates the host-side
|
|
// bind mount source folders, and it is safe to re-run. Host prerequisite:
|
|
// Node on PATH. That is the only host-side tool needed beyond Docker Desktop
|
|
// and the VS Code Dev Containers extension.
|
|
"initializeCommand": "node .devcontainer/ensure-host-config-dirs.cjs",
|
|
|
|
"features": {
|
|
"ghcr.io/devcontainers/features/github-cli:1": {}
|
|
},
|
|
|
|
"remoteUser": "node",
|
|
"updateRemoteUserUID": true,
|
|
|
|
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
|
|
"workspaceFolder": "/workspace",
|
|
|
|
// 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
|
|
// 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).
|
|
//
|
|
// 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
|
|
// to the default ~/.claude, which is this same path. Credentials,
|
|
// identity, and single config files (.credentials.json,
|
|
// ~/.claude/.claude.json, settings.json, config.toml, cli-config.json,
|
|
// mcp.json) live here with correct Linux permissions. They are NOT
|
|
// bind-mounted, because single-file binds break on Docker Desktop Windows
|
|
// (the EXDEV error — see the SINGLE-FILE note below). Container-managed
|
|
// state (sessions, history, caches, IDE locks) stays separate per
|
|
// devcontainer. So two GitNexus checkouts on the same host can't corrupt
|
|
// each other.
|
|
//
|
|
// 3. Other host config — read-only bind mounts for credential and identity
|
|
// folders that lack the permission-flattening and onboarding-state
|
|
// complications Claude Code has (ssh, aws, azure, git config, plus gh and
|
|
// docker). gh and docker are read-only so a compromised dependency can't
|
|
// rewrite the GitHub token or the Docker credHelper. See the inline note
|
|
// at those mounts. `~/.gitconfig` is not mounted here. VS Code auto-copies
|
|
// it separately.
|
|
//
|
|
// 4. Per-instance state — scoped by `${devcontainerId}`: shell history and
|
|
// the npm cache. These survive rebuilds and stay separate between sibling
|
|
// instances.
|
|
//
|
|
// 5. Per-workspace-name AND per-instance state — the workspace `node_modules`
|
|
// volumes use both `${localWorkspaceFolderBasename}` (so you can spot them
|
|
// in `docker volume ls`) and `${devcontainerId}` (so sibling instances of
|
|
// the same repo never collide). This keeps tree-sitter native binaries and
|
|
// onnxruntime off the workspace bind mount, which is faster on Windows and
|
|
// macOS.
|
|
"mounts": [
|
|
// One named volume per container for credentials and identity state. Each
|
|
// CLI's real `~/.<cli>` config folder lives in a volume. That keeps
|
|
// credentials (with correct Linux 600 permissions) and per-container
|
|
// session state separate from the host. Logging in inside the container
|
|
// and logging in on the host are independent. The bind mounts BELOW these
|
|
// volumes override the volume's contents at the paths they cover. Docker
|
|
// mount precedence is: the more specific path wins.
|
|
"source=claude-config-${devcontainerId},target=/home/node/.claude,type=volume",
|
|
"source=codex-config-${devcontainerId},target=/home/node/.codex,type=volume",
|
|
"source=cursor-config-${devcontainerId},target=/home/node/.cursor,type=volume",
|
|
|
|
// 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.
|
|
"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",
|
|
|
|
// 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",
|
|
//
|
|
// SINGLE-FILE binds for settings.json, .claude.json, and config.toml are
|
|
// deliberately ABSENT. On Docker Desktop Windows the named volume sits on
|
|
// one filesystem (ext4, /dev/sdd) and a single-file bind from the host sits
|
|
// on another (the 9p drvfs share). Apps save a config by writing `foo.tmp`
|
|
// and renaming it over `foo`. That rename can't cross filesystems: it hits
|
|
// the EXDEV error and fails with `Device or resource busy` or `inter-device
|
|
// move failed`. Codex's TUI shows this as "config/batchWrite failed in
|
|
// TUI"; Claude just silently loses the write the same way. Instead, we use
|
|
// a read-only host stage at /host/.claude, and post-create.sh copies these
|
|
// files into the named volume on every container-create. Host changes show
|
|
// up on the next rebuild. Container changes stay inside the container until
|
|
// a rebuild.
|
|
"source=${localEnv:HOME}/.claude.json,target=/host/.claude.json,type=bind,readonly",
|
|
"source=${localEnv:HOME}/.config/git,target=/home/node/.config/git,type=bind,readonly",
|
|
"source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,readonly",
|
|
// gh and docker are READ-ONLY. The container reads your EXISTING host login,
|
|
// which is the common case. But a compromised in-container dependency can't
|
|
// rewrite ~/.config/gh/hosts.yml (your GitHub token) or
|
|
// ~/.docker/config.json (the registry credHelper, which points at a
|
|
// binary). The trade-off: `gh auth login` or `docker login` run INSIDE the
|
|
// container won't persist back to the host. Re-run them on the host, or
|
|
// remove `,readonly` from the next two lines if you want in-container logins
|
|
// to stick. See README § Trust boundary.
|
|
"source=${localEnv:HOME}/.config/gh,target=/home/node/.config/gh,type=bind,readonly",
|
|
"source=${localEnv:HOME}/.docker,target=/home/node/.docker,type=bind,readonly",
|
|
"source=${localEnv:HOME}/.aws,target=/home/node/.aws,type=bind,readonly",
|
|
"source=${localEnv:HOME}/.azure,target=/home/node/.azure,type=bind,readonly",
|
|
"source=commandhistory-${devcontainerId},target=/commandhistory,type=volume",
|
|
"source=npm-cache-${devcontainerId},target=/home/node/.npm,type=volume",
|
|
"source=${localWorkspaceFolderBasename}-root-node-modules-${devcontainerId},target=/workspace/node_modules,type=volume",
|
|
"source=${localWorkspaceFolderBasename}-gitnexus-node-modules-${devcontainerId},target=/workspace/gitnexus/node_modules,type=volume",
|
|
"source=${localWorkspaceFolderBasename}-gitnexus-web-node-modules-${devcontainerId},target=/workspace/gitnexus-web/node_modules,type=volume",
|
|
"source=${localWorkspaceFolderBasename}-gitnexus-shared-node-modules-${devcontainerId},target=/workspace/gitnexus-shared/node_modules,type=volume"
|
|
],
|
|
|
|
// Interactive login is the default way to authenticate for all three CLIs.
|
|
// Credentials live in the per-container named volumes (claude-config,
|
|
// 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.
|
|
// 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
|
|
// this empty key" instead of "fall back to the stored login", which would
|
|
// silently break `cursor-agent login`. If you need API-key auth, `export`
|
|
// the var in your container shell, or carry it in your VS Code dotfiles repo
|
|
// (see .devcontainer/README.md).
|
|
// CLAUDE_CONFIG_DIR is left unset on purpose. The Claude default is
|
|
// `$HOME/.claude` (= `/home/node/.claude`), which is exactly where the
|
|
// claude-config named volume mounts. Setting the env var would change which
|
|
// file Claude reads `hasCompletedOnboarding` from. With the var set, Claude
|
|
// reads `$CLAUDE_CONFIG_DIR/.claude.json`, the small identity file. Without
|
|
// it, Claude reads `$HOME/.claude.json`, the big onboarding-state file that
|
|
// actually holds `hasCompletedOnboarding`, the user-scope MCP config, and
|
|
// per-project trust. Leaving the var unset matches host behavior. It also
|
|
// lets post-create.sh's sync of `$HOME/.claude.json` skip the setup wizard
|
|
// on every container-create.
|
|
//
|
|
// CODEX_HOME is kept even though it matches the Codex default, as a canary.
|
|
// If we ever move the Codex named volume target, this env var makes the
|
|
// dependency explicit instead of silently following the default.
|
|
"containerEnv": {
|
|
"CODEX_HOME": "/home/node/.codex",
|
|
"DISABLE_AUTOUPDATER": "1",
|
|
// post-create.sh removes `installMethod` from the seeded ~/.claude.json so
|
|
// the npm-global binary detects its own install method. This is a backup
|
|
// safeguard for Claude Code issue #17289. The install-checks routine probes
|
|
// ~/.local/bin/claude just because that directory EXISTS. It does exist
|
|
// here, because Cursor drops agent and cursor-agent symlinks there. So even
|
|
// when installMethod is non-native, the routine reports a false "claude
|
|
// command not found at ~/.local/bin/claude". DISABLE_AUTOUPDATER does NOT
|
|
// turn that routine off. DISABLE_INSTALLATION_CHECKS is its dedicated kill
|
|
// switch.
|
|
"DISABLE_INSTALLATION_CHECKS": "1",
|
|
"HISTFILE": "/commandhistory/.zsh_history"
|
|
},
|
|
|
|
"customizations": {
|
|
"vscode": {
|
|
"extensions": [
|
|
"anthropic.claude-code",
|
|
"dbaeumer.vscode-eslint",
|
|
"esbenp.prettier-vscode",
|
|
"eamodio.gitlens"
|
|
],
|
|
"settings": {
|
|
"editor.formatOnSave": true,
|
|
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
|
"editor.codeActionsOnSave": {
|
|
"source.fixAll.eslint": "explicit"
|
|
},
|
|
"files.eol": "\n",
|
|
"terminal.integrated.defaultProfile.linux": "zsh",
|
|
"terminal.integrated.profiles.linux": {
|
|
"bash": { "path": "bash", "icon": "terminal-bash" },
|
|
"zsh": { "path": "zsh" }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
|
|
// Do not remap port 4747 (gitnexus serve). gitnexus-web hardcodes
|
|
// http://localhost:4747 as its default backend URL.
|
|
"forwardPorts": [5173, 4747, 4173],
|
|
"portsAttributes": {
|
|
"5173": {
|
|
"label": "Vite dev (gitnexus-web)",
|
|
"onAutoForward": "notify"
|
|
},
|
|
"4747": {
|
|
"label": "gitnexus serve HTTP API",
|
|
"onAutoForward": "notify",
|
|
"requireLocalPort": true
|
|
},
|
|
"4173": {
|
|
"label": "Static web (Vite preview)",
|
|
"onAutoForward": "silent"
|
|
}
|
|
},
|
|
|
|
// Lifecycle split (from the Dev Container spec):
|
|
// - `updateContentCommand` runs on container-create AND whenever the
|
|
// workspace content changes, such as a lockfile update. It owns installing
|
|
// the workspace dependencies. Re-installing on every container-create
|
|
// wastes time when nothing changed, but it must re-run when deps change.
|
|
// - `postCreateCommand` runs once on container-create. It owns syncing the
|
|
// AI CLI credentials and identity from the host. That work should happen
|
|
// exactly once per container instance, not on every content update.
|
|
// Run both with an explicit `bash` so they don't depend on the script's
|
|
// executable bit surviving the workspace bind mount.
|
|
"updateContentCommand": "bash .devcontainer/install-deps.sh",
|
|
"postCreateCommand": "bash .devcontainer/post-create.sh"
|
|
}
|