Add secure devcontainer setup for Claude Code CLI

- Configure devcontainer with Node.js 20, Claude Code CLI, and dev tools
- Add firewall script to restrict network access to whitelisted domains
- Create run-container.sh helper for interactive and non-interactive usage
- Support interactive mode (no args) for authentication/credential storage
- Support non-interactive mode with prompt argument or stdin

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.devcontainer/Dockerfile

@@ -0,0 +1,91 @@
+FROM node:20
+
+ARG TZ
+ENV TZ="$TZ"
+
+ARG CLAUDE_CODE_VERSION=latest
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  less \
+  git \
+  procps \
+  sudo \
+  fzf \
+  zsh \
+  man-db \
+  unzip \
+  gnupg2 \
+  gh \
+  iptables \
+  ipset \
+  iproute2 \
+  dnsutils \
+  aggregate \
+  jq \
+  nano \
+  vim \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Ensure default node user has access to /usr/local/share
+RUN mkdir -p /usr/local/share/npm-global && \
+  chown -R node:node /usr/local/share
+
+ARG USERNAME=node
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  && mkdir /commandhistory \
+  && touch /commandhistory/.bash_history \
+  && chown -R $USERNAME /commandhistory
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+# Create workspace and config directories and set permissions
+RUN mkdir -p /workspace /home/node/.claude && \
+  chown -R node:node /workspace /home/node/.claude
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# Set up non-root user
+USER node
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
+  -p git \
+  -p fzf \
+  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
+  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -x
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
+
+
+# Copy and set up firewall script
+COPY init-firewall.sh /usr/local/bin/
+USER root
+RUN chmod +x /usr/local/bin/init-firewall.sh && \
+  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
+  chmod 0440 /etc/sudoers.d/node-firewall
+USER node

.devcontainer/devcontainer.json

@@ -0,0 +1,57 @@
+{
+  "name": "Claude Code Sandbox",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "${localEnv:TZ:America/Los_Angeles}",
+      "CLAUDE_CODE_VERSION": "latest",
+      "GIT_DELTA_VERSION": "0.18.2",
+      "ZSH_IN_DOCKER_VERSION": "1.2.0"
+    }
+  },
+  "runArgs": [
+    "--cap-add=NET_ADMIN",
+    "--cap-add=NET_RAW"
+  ],
+  "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"
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        }
+      }
+    }
+  },
+  "remoteUser": "node",
+  "mounts": [
+    "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
+    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
+  ],
+  "containerEnv": {
+    "NODE_OPTIONS": "--max-old-space-size=4096",
+    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
+    "POWERLEVEL9K_DISABLE_GITSTATUS": "true"
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
+  "workspaceFolder": "/workspace",
+  "postStartCommand": "sudo /usr/local/bin/init-firewall.sh",
+  "waitFor": "postStartCommand"
+}

.devcontainer/init-firewall.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
+IFS=$'\n\t'       # Stricter word splitting
+
+# 1. Extract Docker DNS info BEFORE any flushing
+DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
+
+# Flush existing rules and delete existing ipsets
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# 2. Selectively restore ONLY internal Docker DNS resolution
+if [ -n "$DOCKER_DNS_RULES" ]; then
+    echo "Restoring Docker DNS rules..."
+    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+    echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
+else
+    echo "No Docker DNS rules to restore"
+fi
+
+# First allow DNS and localhost before any restrictions
+# Allow outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+# Allow inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+# Allow outbound SSH
+iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
+# Allow inbound SSH responses
+iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
+# Allow localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Create ipset with CIDR support
+ipset create allowed-domains hash:net
+
+# Fetch GitHub meta information and aggregate + add their IP ranges
+echo "Fetching GitHub IP ranges..."
+gh_ranges=$(curl -s https://api.github.com/meta)
+if [ -z "$gh_ranges" ]; then
+    echo "ERROR: Failed to fetch GitHub IP ranges"
+    exit 1
+fi
+
+if ! echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null; then
+    echo "ERROR: GitHub API response missing required fields"
+    exit 1
+fi
+
+echo "Processing GitHub IPs..."
+while read -r cidr; do
+    if [[ ! "$cidr" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$ ]]; then
+        echo "ERROR: Invalid CIDR range from GitHub meta: $cidr"
+        exit 1
+    fi
+    echo "Adding GitHub range $cidr"
+    ipset add allowed-domains "$cidr"
+done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q)
+
+# Resolve and add other allowed domains
+for domain in \
+    "registry.npmjs.org" \
+    "api.anthropic.com" \
+    "sentry.io" \
+    "statsig.anthropic.com" \
+    "statsig.com" \
+    "marketplace.visualstudio.com" \
+    "vscode.blob.core.windows.net" \
+    "update.code.visualstudio.com"; do
+    echo "Resolving $domain..."
+    ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+    if [ -z "$ips" ]; then
+        echo "ERROR: Failed to resolve $domain"
+        exit 1
+    fi
+
+    while read -r ip; do
+        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            echo "ERROR: Invalid IP from DNS for $domain: $ip"
+            exit 1
+        fi
+        echo "Adding $ip for $domain"
+        ipset add allowed-domains "$ip"
+    done < <(echo "$ips")
+done
+
+# Get host IP from default route
+HOST_IP=$(ip route | grep default | cut -d" " -f3)
+if [ -z "$HOST_IP" ]; then
+    echo "ERROR: Failed to detect host IP"
+    exit 1
+fi
+
+HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
+echo "Host network detected as: $HOST_NETWORK"
+
+# Set up remaining iptables rules
+iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+
+# Set default policies to DROP first
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# First allow established connections for already approved traffic
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Then allow only specific outbound traffic to allowed domains
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+# Explicitly REJECT all other outbound traffic for immediate feedback
+iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
+
+echo "Firewall configuration complete"
+echo "Verifying firewall rules..."
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://example.com as expected"
+fi
+
+# Verify GitHub API access
+if ! curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.github.com"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.github.com as expected"
+fi

CLAUDE.md

@@ -0,0 +1,133 @@
+# 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:
+
+```bash
+# 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:
+```bash
+npm install -g @devcontainers/cli
+```
+
+Build and run the container:
+```bash
+# 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:
+```bash
+# 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:
+
+```bash
+# 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](https://mise.jdx.dev/) for tool version management.
+
+- Node.js version: 24 (configured in `mise.toml`)
+- Install tools: `mise install`

mise.toml

@@ -0,0 +1,2 @@
+[tools]
+node = "24"

run-container.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+set -euo pipefail
+
+# Script to run Claude Code in a secure devcontainer
+# Usage: ./run-container.sh "your prompt here"
+# Or with stdin: echo "your prompt" | ./run-container.sh
+
+IMAGE_NAME="claude-dev-container"
+CONTAINER_NAME="claude-dev-container-$$"
+VOLUME_HISTORY="claude-code-bashhistory"
+VOLUME_CONFIG="claude-code-config"
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Function to print colored messages
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check if Docker is available
+if ! command -v docker &> /dev/null; then
+    log_error "Docker is not installed or not in PATH"
+    exit 1
+fi
+
+# Build image if it doesn't exist
+if ! docker image inspect "$IMAGE_NAME" &> /dev/null; then
+    log_info "Image '$IMAGE_NAME' not found. Building..."
+    docker build -t "$IMAGE_NAME" .devcontainer
+    log_info "Image built successfully"
+else
+    log_info "Using existing image '$IMAGE_NAME'"
+fi
+
+# Create volumes if they don't exist
+if ! docker volume inspect "$VOLUME_HISTORY" &> /dev/null; then
+    log_info "Creating volume '$VOLUME_HISTORY'"
+    docker volume create "$VOLUME_HISTORY" > /dev/null
+fi
+
+if ! docker volume inspect "$VOLUME_CONFIG" &> /dev/null; then
+    log_info "Creating volume '$VOLUME_CONFIG'"
+    docker volume create "$VOLUME_CONFIG" > /dev/null
+fi
+
+# Get the prompt from arguments or stdin
+PROMPT=""
+if [ $# -gt 0 ]; then
+    # Use arguments as prompt
+    PROMPT="$*"
+elif [ ! -t 0 ]; then
+    # Read from stdin if available
+    PROMPT=$(cat)
+fi
+
+# Check if running in interactive mode (no prompt provided)
+if [ -z "$PROMPT" ]; then
+    log_info "No prompt provided. Starting interactive mode..."
+    log_info "You can now run 'claude' to authenticate or use Claude Code interactively"
+
+    # Run the container in interactive mode
+    docker run --rm -it \
+        --name "$CONTAINER_NAME" \
+        --cap-add=NET_ADMIN \
+        --cap-add=NET_RAW \
+        -v "$(pwd):/workspace" \
+        -v "$VOLUME_HISTORY:/commandhistory" \
+        -v "$VOLUME_CONFIG:/home/node/.claude" \
+        -e NODE_OPTIONS="--max-old-space-size=4096" \
+        -e CLAUDE_CONFIG_DIR="/home/node/.claude" \
+        -e POWERLEVEL9K_DISABLE_GITSTATUS="true" \
+        -w /workspace \
+        --user node \
+        "$IMAGE_NAME" \
+        /bin/bash -c "
+            # Initialize firewall
+            echo 'Initializing firewall...'
+            sudo /usr/local/bin/init-firewall.sh
+
+            echo ''
+            echo 'Container ready! Firewall initialized.'
+            echo 'Run \"claude\" to authenticate or use Claude Code interactively.'
+            echo 'Type \"exit\" to leave the container.'
+            echo ''
+
+            # Start interactive shell
+            exec zsh
+        "
+    exit $?
+fi
+
+log_info "Running Claude Code in container..."
+
+# Run the container with the command
+# The command will: initialize firewall, then run claude
+docker run --rm \
+    --name "$CONTAINER_NAME" \
+    --cap-add=NET_ADMIN \
+    --cap-add=NET_RAW \
+    -v "$(pwd):/workspace" \
+    -v "$VOLUME_HISTORY:/commandhistory" \
+    -v "$VOLUME_CONFIG:/home/node/.claude" \
+    -e NODE_OPTIONS="--max-old-space-size=4096" \
+    -e CLAUDE_CONFIG_DIR="/home/node/.claude" \
+    -e POWERLEVEL9K_DISABLE_GITSTATUS="true" \
+    -w /workspace \
+    --user node \
+    "$IMAGE_NAME" \
+    /bin/bash -c "
+        # Initialize firewall
+        echo 'Initializing firewall...' >&2
+        sudo /usr/local/bin/init-firewall.sh >&2
+
+        # Run claude with the prompt
+        echo 'Running Claude Code...' >&2
+        claude -p \"$PROMPT\" --dangerously-skip-permissions
+    "
+
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+    log_info "Command completed successfully"
+else
+    log_error "Command failed with exit code $EXIT_CODE"
+    exit $EXIT_CODE
+fi