This page documents the DevContainer configuration defined in .devcontainer/devcontainer.json, which establishes a reproducible, secure development environment for Claude Code. The configuration specifies build parameters, VS Code customizations, persistent storage volumes, environment variables, and container lifecycle hooks.
For network security and firewall rules, see Network Security & Firewall. For the base Docker image and tooling installation, see Base Image & Tooling. For container orchestration and startup scripts, see Container Orchestration.
The .devcontainer/devcontainer.json file defines all aspects of the containerized development environment, from build arguments to runtime security capabilities to VS Code integration.
Sources: .devcontainer/devcontainer.json1-57
The build section references the Dockerfile and passes build-time arguments that customize the container image.
| Build Argument | Default Value | Purpose |
|---|---|---|
TZ | ${localEnv:TZ:America/Los_Angeles} | Sets container timezone from host environment or defaults to Pacific |
CLAUDE_CODE_VERSION | latest | Specifies which version of @anthropic-ai/claude-code npm package to install |
GIT_DELTA_VERSION | 0.18.2 | Version of git-delta diff viewer to install |
ZSH_IN_DOCKER_VERSION | 1.2.0 | Version of zsh-in-docker installer to use |
The dockerfile property points to the Dockerfile in the same directory .devcontainer/devcontainer.json4 The timezone parameter uses the DevContainer variable substitution syntax ${localEnv:TZ:default} to read from the host's TZ environment variable .devcontainer/devcontainer.json6
Sources: .devcontainer/devcontainer.json3-10
The container requires two Linux capabilities for network firewall configuration:
iptables and ipset operations that configure network filtering rulesThese capabilities are minimally scoped - the container does not run with full root privileges. The node user can only execute the firewall initialization script via sudo .devcontainer/devcontainer.json12-15
Sources: .devcontainer/devcontainer.json12-15 .devcontainer/Dockerfile89
Four extensions are automatically installed in the container:
| Extension ID | Purpose |
|---|---|
anthropic.claude-code | Claude Code VS Code extension for AI-assisted development |
dbaeumer.vscode-eslint | ESLint integration for JavaScript/TypeScript linting |
esbenp.prettier-vscode | Prettier code formatter |
eamodio.gitlens | Git visualization and history exploration |
These extensions are specified in the customizations.vscode.extensions array .devcontainer/devcontainer.json18-23
Sources: .devcontainer/devcontainer.json18-23 .vscode/extensions.json1-8
The DevContainer applies workspace-level VS Code settings:
Sources: .devcontainer/devcontainer.json24-40
The container provides two shell profiles with zsh as default:
The zsh configuration includes fzf key bindings for interactive file/command search and bash history persistence .devcontainer/Dockerfile76-78
Sources: .devcontainer/devcontainer.json30-39 .devcontainer/Dockerfile64-79
The DevContainer uses three persistent storage mechanisms:
Two Docker named volumes preserve state across container rebuilds:
Bash History Volume: claude-code-bashhistory-${devcontainerId} → /commandhistory
.bash_history file .devcontainer/devcontainer.json45HISTFILE environment variable .devcontainer/Dockerfile78Claude Configuration Volume: claude-code-config-${devcontainerId} → /home/node/.claude
CLAUDE_CONFIG_DIR environment variable .devcontainer/devcontainer.json50The ${devcontainerId} variable ensures each DevContainer instance has isolated volumes, preventing configuration conflicts when multiple instances run simultaneously.
Sources: .devcontainer/devcontainer.json44-47 .devcontainer/Dockerfile36-47
The local workspace folder is bind-mounted into the container:
delegated optimizes for host-to-container writes, reducing I/O latency on macOS .devcontainer/devcontainer.json53/workspace .devcontainer/devcontainer.json54Sources: .devcontainer/devcontainer.json53-54 .devcontainer/Dockerfile49
The containerEnv section defines environment variables set in the container runtime:
| Variable | Value | Purpose |
|---|---|---|
NODE_OPTIONS | --max-old-space-size=4096 | Allocates 4GB heap for Node.js processes .devcontainer/devcontainer.json49 |
CLAUDE_CONFIG_DIR | /home/node/.claude | Specifies Claude Code configuration directory .devcontainer/devcontainer.json50 |
POWERLEVEL9K_DISABLE_GITSTATUS | true | Disables git status in prompt for performance .devcontainer/devcontainer.json51 |
Sources: .devcontainer/devcontainer.json48-52
The Dockerfile sets additional environment variables in the image:
| Variable | Value | Purpose |
|---|---|---|
DEVCONTAINER | true | Identifies runtime environment as DevContainer .devcontainer/Dockerfile43 |
NPM_CONFIG_PREFIX | /usr/local/share/npm-global | Sets npm global package installation path .devcontainer/Dockerfile61 |
PATH | Extended with npm global bin | Includes globally installed npm packages .devcontainer/Dockerfile62 |
SHELL | /bin/zsh | Sets default shell for non-login sessions .devcontainer/Dockerfile65 |
EDITOR | nano | Default text editor for command-line operations .devcontainer/Dockerfile68 |
VISUAL | nano | Visual editor for interactive operations .devcontainer/Dockerfile69 |
TZ | Build argument value | Container timezone .devcontainer/Dockerfile4 |
Sources: .devcontainer/Dockerfile4-69
The DevContainer executes a critical initialization step after the container starts:
The postStartCommand runs the firewall initialization script .devcontainer/devcontainer.json55 which:
The waitFor: "postStartCommand" setting ensures the container is not considered ready until firewall setup completes .devcontainer/devcontainer.json56 This prevents Claude Code from executing commands before network security is enforced.
For detailed firewall configuration, see Network Security & Firewall.
Sources: .devcontainer/devcontainer.json55-56 .devcontainer/init-firewall.sh1-138
Sources: .devcontainer/devcontainer.json1-57 .devcontainer/Dockerfile1-92 .devcontainer/init-firewall.sh1-138
The container runs as the non-root node user for security:
This setting ensures:
node user .devcontainer/devcontainer.json43The node user is created by the base node:20 image and configured in the Dockerfile with ownership of /workspace, /home/node/.claude, and /usr/local/share/npm-global directories .devcontainer/Dockerfile31-47
Sources: .devcontainer/devcontainer.json43 .devcontainer/Dockerfile31-91
The DevContainer configuration uses several variable substitution patterns:
| Variable | Syntax | Example | Purpose |
|---|---|---|---|
| Local environment | ${localEnv:VAR:default} | ${localEnv:TZ:America/Los_Angeles} | Read from host environment with fallback |
| Local workspace | ${localWorkspaceFolder} | /Users/dev/project | Host path to workspace root |
| Container ID | ${devcontainerId} | abc123def456 | Unique identifier for volume isolation |
These variables are resolved by VS Code when the DevContainer is created, enabling dynamic configuration based on the host environment.
Sources: .devcontainer/devcontainer.json6-53
Refresh this wiki