Claude Code Devcontainer

A minimal, secure devcontainer setup for development with Claude Code in VSCode.

What's Included

• Node.js 20 base environment
• Claude Code CLI pre-installed (latest version)
• Development tools: git, zsh with Oh My Zsh, fzf, git-delta, GitHub CLI, vim, nano
• VSCode extension: Claude Code
• Network firewall: Restricts outbound connections to approved domains (GitHub, npm, Anthropic API, etc.)
• Persistent volumes: Bash history and Claude config persisted across container rebuilds

Features

Secure Network Sandbox

The devcontainer includes a firewall (init-firewall.sh) that automatically restricts network access to specific approved domains. This provides a secure sandboxed environment for AI-assisted development.

Zsh with Oh My Zsh

The default shell is zsh with Oh My Zsh pre-configured with:

• git and fzf plugins
• Persistent command history
• Customizable prompt (modify Dockerfile to add more plugins)

Persistent Storage

• Command history persists across container rebuilds
• Claude configuration directory (~/.claude) is preserved in a named volume

Usage

Option 1: Use as Template

1. Click "Use this template" on GitHub to create a new repository
2. Clone your new repository
3. Open in VSCode with Dev Containers extension
4. VSCode will build and start the devcontainer

Option 2: Clone and Customize

# Clone this repo
git clone <this-repo-url> my-project
cd my-project

# Optional: Remove git history to start fresh
rm -rf .git
git init
git add .
git commit -m "Initial commit"

# Add your remote
git remote add origin <your-repo-url>

Configuration

VSCode Extensions

Currently includes only Claude Code. To add more extensions, edit .devcontainer/devcontainer.json:

"extensions": [
  "anthropic.claude-code",
  "dbaeumer.vscode-eslint",
  "esbenp.prettier-vscode"
]

Installing Additional Tools

Edit .devcontainer/Dockerfile to add packages:

RUN apt-get update && apt-get install -y \
  your-package-here \
  && apt-get clean && rm -rf /var/lib/apt/lists/*

Network Firewall Rules

To allow additional domains, edit .devcontainer/init-firewall.sh and add domains to the appropriate list.

Known Limitations

Git Commit Signing

Git commit signing is not configured in this devcontainer. If you need signed commits:

• Recommended: Disable signing in the container by adding to postStartCommand: git config --global commit.gpgsign false
• Alternative: Set up GPG signing with GPG agent forwarding (more complex)

SSH Agent Forwarding

VSCode handles SSH agent forwarding automatically for git operations. Ensure your SSH keys are loaded in your host SSH agent before starting the container.

Environment Variables

The following environment variables are configured:

• NODE_OPTIONS="--max-old-space-size=4096" - Increases Node.js memory limit
• CLAUDE_CONFIG_DIR="/home/node/.claude" - Claude configuration directory
• POWERLEVEL9K_DISABLE_GITSTATUS="true" - Disables git status in prompt (performance)
• DEVCONTAINER="true" - Indicates running in a devcontainer

Troubleshooting

Container fails to build

• Check Docker daemon is running
• Ensure you have enough disk space
• Try rebuilding: Ctrl+Shift+P → "Dev Containers: Rebuild Container"

Firewall blocking needed connections

• Check .devcontainer/init-firewall.sh
• Add your domain to the appropriate allowlist
• Rebuild the container

Claude Code not working

• Ensure you've authenticated: run claude auth in the terminal
• Check your API key is valid
• Verify network connectivity to Anthropic API