claude-dev-container/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Container Setup

This repository is configured with a secure development container based on Anthropic's reference devcontainer setup. The container provides:

• Isolated environment: Containerized Claude Code CLI with firewall restrictions
• Security features: Network access limited to whitelisted domains (GitHub, npm, Anthropic APIs, etc.)
• Pre-configured tools: Node.js 20, Claude Code CLI, git-delta, zsh with powerline10k, fzf, and more
• Persistent storage: Volumes for bash history and Claude configuration

Opening in DevContainer

Option 1: Using run-container.sh script (easiest for non-interactive usage)

The repository includes a helper script for running Claude Code non-interactively:

# Make the script executable (first time only)
chmod +x run-container.sh

# Run with a prompt
./run-container.sh "explain the fibonacci sequence"

# Run with stdin
echo "create a hello world function in Python" | ./run-container.sh

# Analyze a file
./run-container.sh "explain this code" < myfile.js

The script automatically:

• Builds the Docker image if needed
• Creates persistent volumes for history and config
• Initializes the firewall
• Runs claude with streaming output and --dangerously-skip-permissions
• Cleans up the container after execution

Option 2: Using devcontainer CLI (recommended for interactive development)

Install the devcontainer CLI:

npm install -g @devcontainers/cli

Build and run the container:

# Build the container
devcontainer build --workspace-folder .

# Run the container and execute a command
devcontainer exec --workspace-folder . claude -p "your prompt" --dangerously-skip-permissions

# Or open an interactive shell
devcontainer exec --workspace-folder . zsh

Option 3: Using Docker directly

Build and run manually:

# Build the image
docker build -t claude-dev-container .devcontainer

# Create volumes for persistence
docker volume create claude-code-bashhistory
docker volume create claude-code-config

# Run interactively
docker run -it --rm \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  -v "$(pwd):/workspace" \
  -v claude-code-bashhistory:/commandhistory \
  -v claude-code-config:/home/node/.claude \
  -e NODE_OPTIONS="--max-old-space-size=4096" \
  -e CLAUDE_CONFIG_DIR="/home/node/.claude" \
  -w /workspace \
  --user node \
  claude-dev-container zsh

# Inside the container, initialize the firewall:
sudo /usr/local/bin/init-firewall.sh

# Then use Claude Code:
claude -p "your prompt" --dangerously-skip-permissions

Option 4: VS Code

1. Install the "Dev Containers" extension
2. Open this repository in VS Code
3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container")
4. Wait for the container to build and the firewall to initialize

First-time setup:

• You'll need to authenticate Claude Code on first use
• Run claude in the container terminal and follow the authentication prompts

Running Claude Code Non-Interactively

The devcontainer's firewall allows running Claude Code with --dangerously-skip-permissions for non-interactive operation:

# Stream output in non-interactive mode
claude -p "your prompt here" --dangerously-skip-permissions

# Example: Analyze a file
claude -p "explain this code" --dangerously-skip-permissions < myfile.js

# Example: Generate code with streaming output
echo "create a fibonacci function" | claude -p --dangerously-skip-permissions

Security notes:

• The --dangerously-skip-permissions flag bypasses permission prompts
• This is safe within the devcontainer due to firewall restrictions
• Network access is limited to: GitHub, npm registry, Anthropic APIs, VS Code services
• All other outbound connections are blocked

Container Configuration Files

• .devcontainer/devcontainer.json - Container and VS Code configuration
• .devcontainer/Dockerfile - Container image definition
• .devcontainer/init-firewall.sh - Network security rules (runs on container start)

Environment Setup (Outside Container)

This repository uses mise for tool version management.

• Node.js version: 24 (configured in mise.toml)
• Install tools: mise install