Development Container Setup

Development containers provide the perfect balance between Claude Code’s powerful automation capabilities and enterprise security requirements. By isolating Claude in a containerized environment, you can safely use --dangerously-skip-permissions for unattended operation while protecting your host system and production credentials.

Why Dev Containers for Claude Code?

Security Isolation

Network firewall restricts external access to approved services only

Consistent Environment

Identical setup across team members regardless of host OS

Permission Freedom

Skip permission prompts safely in isolated container

Quick Onboarding

New developers productive in minutes, not hours

Quick Start

1. Install prerequisites

   • VS Code with Remote - Containers extension
   • Docker Desktop (or compatible container runtime)
   • Git for cloning the reference implementation

2. Clone reference implementation

   git clone https://github.com/anthropics/claude-code.git
   cd claude-code/.devcontainer

3. Open in VS Code

   code .

4. Reopen in container

   • Click “Reopen in Container” when prompted
   • Or use Command Palette: Remote-Containers: Reopen in Container

Claude Code automatically installs and configures itself in the container, ready for immediate use with enhanced security.

Container Architecture

The reference implementation consists of three core components:

devcontainer.json Configuration

{
  "name": "Claude Code Dev Container",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "terminal.integrated.defaultProfile.linux": "zsh",
        "editor.formatOnSave": true
      }
    }
  },
  "postCreateCommand": ".devcontainer/init-firewall.sh",
  "remoteUser": "vscode",
  "mounts": [
    "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached",
    "source=claude-history,target=/home/vscode/.claude,type=volume"
  ],
  "runArgs": ["--cap-add=NET_ADMIN"]
}

Dockerfile Structure

FROM mcr.microsoft.com/devcontainers/javascript-node:20

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    zsh \
    fzf \
    ripgrep \
    iptables \
    && rm -rf /var/lib/apt/lists/*

# Configure shell enhancements
RUN sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Install Claude Code globally
RUN npm install -g @anthropic-ai/claude-code

# Create non-root user
ARG USERNAME=vscode
ARG USER_UID=1000
ARG USER_GID=$USER_UID

RUN groupadd --gid $USER_GID $USERNAME \
    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME \
    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME

USER $USERNAME

Security Firewall Configuration

The init-firewall.sh script implements a strict default-deny firewall:

#!/bin/bash

# Reset firewall rules
sudo iptables -F
sudo iptables -X

# Default policies: deny all
sudo iptables -P INPUT DROP
sudo iptables -P FORWARD DROP
sudo iptables -P OUTPUT DROP

# Allow loopback
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT

# Allow established connections
sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Whitelist essential services
ALLOWED_DOMAINS=(
  "api.anthropic.com"           # Claude API
  "statsig.anthropic.com"       # Telemetry
  "registry.npmjs.org"          # npm packages
  "github.com"                  # Git operations
  "raw.githubusercontent.com"   # Raw file access
)

for domain in "${ALLOWED_DOMAINS[@]}"; do
  # Resolve and allow each IP
  for ip in $(dig +short $domain A); do
    sudo iptables -A OUTPUT -d $ip -j ACCEPT
  done
done

# Allow DNS queries
sudo iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

# Allow SSH for git
sudo iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT

echo "✅ Firewall configured with restricted access"

Caution

The firewall provides substantial protection but isn’t completely immune to all attacks. Only use with trusted repositories and maintain security monitoring.

Customization Guide

Adding Development Tools

Extend the Dockerfile to include your team’s standard toolset:

Python Development

# Add Python development environment
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    && rm -rf /var/lib/apt/lists/*

# Install common Python tools
RUN pip3 install --user \
    black \
    flake8 \
    mypy \
    pytest

Go Development

# Install Go
RUN curl -OL https://go.dev/dl/go1.21.linux-amd64.tar.gz \
    && sudo tar -C /usr/local -xzf go1.21.linux-amd64.tar.gz \
    && rm go1.21.linux-amd64.tar.gz

ENV PATH=$PATH:/usr/local/go/bin

# Install Go tools
RUN go install golang.org/x/tools/gopls@latest
RUN go install github.com/go-delve/delve/cmd/dlv@latest

Rust Development

# Install Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

ENV PATH="/home/vscode/.cargo/bin:${PATH}"

# Install additional components
RUN rustup component add rustfmt clippy

Configuring Network Access

Modify firewall rules for your organization’s needs:

# Add private registry access
PRIVATE_REGISTRY="registry.company.com"
for ip in $(dig +short $PRIVATE_REGISTRY A); do
  sudo iptables -A OUTPUT -d $ip -j ACCEPT
done

# Add internal API access
sudo iptables -A OUTPUT -d 10.0.0.0/8 -j ACCEPT    # Private network
sudo iptables -A OUTPUT -d 172.16.0.0/12 -j ACCEPT # Docker networks

# Add specific ports for services
sudo iptables -A OUTPUT -p tcp --dport 5432 -j ACCEPT # PostgreSQL
sudo iptables -A OUTPUT -p tcp --dport 6379 -j ACCEPT # Redis

Volume Mounts and Persistence

Configure persistent storage for different scenarios:

{
  "mounts": [
    // SSH keys for git operations
    "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,readonly",

    // AWS credentials (if needed)
    "source=${localEnv:HOME}/.aws,target=/home/vscode/.aws,type=bind,readonly",

    // Persistent Claude history
    "source=claude-history,target=/home/vscode/.claude,type=volume",

    // Shared team configuration
    "source=${localWorkspaceFolder}/.devcontainer/team-config,target=/home/vscode/.config/team,type=bind,readonly"
  ]
}

Enterprise Integration

Corporate Proxy Support

Configure proxy settings in the container:

# Add to Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV NO_PROXY=${NO_PROXY}

# Configure npm for proxy
RUN if [ -n "$HTTP_PROXY" ]; then \
    npm config set proxy $HTTP_PROXY && \
    npm config set https-proxy $HTTPS_PROXY; \
    fi

Team-Wide Configuration

Share consistent Claude Code settings:

.devcontainer/team-config/claude-settings.json

{
  "permissions": {
    "allow": ["*"],  // Safe in isolated container
    "deny": []
  },
  "env": {
    "CLAUDE_CODE_ENABLE_AUDIT_LOGGING": "1"
  },
  "hooks": {
    "PreEdit": "npm run lint --fix",
    "PostEdit": "npm run format"
  }
}

Mount and apply in postCreateCommand:

# Copy team settings
cp /home/vscode/.config/team/claude-settings.json ~/.claude/settings.json

Security Best Practices

Credential Management

Never include credentials in container images. Use volume mounts or environment variables.

Image Scanning

Regularly scan container images for vulnerabilities using tools like Trivy or Snyk.

Least Privilege

Run containers as non-root users and limit capabilities to minimum required.

Network Monitoring

Log and monitor outbound connections to detect unusual activity.

Monitoring Container Activity

Add logging to track Claude’s actions:

# Add to init-firewall.sh
# Log all accepted connections
sudo iptables -A OUTPUT -j LOG --log-prefix "CLAUDE-ALLOW: " --log-level 4

# Log all rejected connections
sudo iptables -A OUTPUT -j LOG --log-prefix "CLAUDE-DENY: " --log-level 4

View logs with:

sudo dmesg | grep CLAUDE-

Common Use Cases

Secure Client Projects

Create isolated environments for different clients:

# Client A container
cd ~/projects/client-a
code .  # Opens with client-a specific devcontainer

# Client B container
cd ~/projects/client-b
code .  # Completely isolated from client-a

Automated Testing Environment

Use devcontainers in CI/CD:

.github/workflows/claude-test.yml

name: Claude Code Testing

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: your-registry/claude-devcontainer:latest
      options: --cap-add=NET_ADMIN

    steps:
      - uses: actions/checkout@v3

      - name: Run Claude Code tests
        run: |
          claude -p "Run all tests and fix any failures"

Team Onboarding

Standardize developer environments:

1. Create team container

   FROM anthropic/claude-devcontainer:base
   
   # Add team-specific tools
   COPY .devcontainer/team-tools.sh /tmp/
   RUN /tmp/team-tools.sh

2. Document in README

   ## Getting Started
   1. Clone this repository
   2. Open in VS Code
   3. Click "Reopen in Container"
   4. Run `claude` to start coding!
   
   Everything is pre-configured - no setup required.

Troubleshooting

Container Build Failures

# Clean rebuild
docker system prune -a
code . # Retry opening in container

# Check Docker resources
docker system df
# Increase Docker Desktop memory if needed

Network Connectivity Issues

# Test DNS resolution
dig api.anthropic.com

# Check firewall rules
sudo iptables -L -n -v

# Verify allowed domains resolve
for domain in api.anthropic.com github.com; do
  echo "Testing $domain:"
  nc -zv $domain 443
done

Permission Problems

# Fix ownership issues
sudo chown -R vscode:vscode /home/vscode

# Reset Claude Code permissions
rm -rf ~/.claude/settings.json
claude logout
claude login

Performance Optimization

Resource Allocation

Configure container resources in Docker Desktop or docker-compose.yml:

version: '3.8'
services:
  devcontainer:
    build: .
    mem_limit: 8g
    cpus: 4
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw

Caching Strategies

Speed up rebuilds with BuildKit cache mounts:

# Cache package downloads
RUN --mount=type=cache,target=/var/cache/apt \
    apt-get update && apt-get install -y git zsh

# Cache npm packages
RUN --mount=type=cache,target=/root/.npm \
    npm install -g @anthropic-ai/claude-code

Next Steps

CI/CD Integration

Automate workflows with Claude in your pipelines

Team Workflows

Scale devcontainer usage across your organization

Security Hardening

Advanced security configurations for containers