Development Container Setup

A new developer joins your team. They spend two days setting up their environment: installing Node.js, configuring PostgreSQL, fighting with Python version managers, and then discovering that Claude Code needs specific environment variables to work with your proxy. Dev containers eliminate this entirely — every developer gets an identical, pre-configured environment with Claude Code ready to go.

What You Will Walk Away With

• A production-ready devcontainer configuration with Claude Code pre-installed
• GitHub Codespaces setup for browser-based Claude Code access
• Patterns for sharing Claude Code configuration across containerized environments
• Security considerations for running Claude Code in containers

Basic Dev Container Setup

The devcontainer.json File

Create .devcontainer/devcontainer.json in your repository:

{
  "name": "Project Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {},
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "postCreateCommand": "npm install && npm run build",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest",
  "forwardPorts": [3000, 5432],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "remoteEnv": {
    "NODE_ENV": "development"
  }
}

Tip

Copy-paste devcontainer.json for a TypeScript project with Claude Code:

{
  "name": "TS + Claude Code",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest && npm install",
  "forwardPorts": [3000],
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
  ]
}

The mounts entry shares your local Claude Code configuration (sessions, settings, memory) with the container.

Tip

Copy-paste prompt to have Claude Code scaffold the devcontainer for you:

Generate a .devcontainer/devcontainer.json for this repo. Detect the package manager and language runtime version from the lockfile and package.json (or equivalent), pre-install Claude Code via postStartCommand, mount ~/.claude with consistency=cached, forward the dev server port, and pass ANTHROPIC_API_KEY through from localEnv. Then explain anything you had to assume.

Run it from inside the repo so Claude reads your actual dependency files rather than guessing.

Custom Dockerfile

For more control, use a Dockerfile:

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/typescript-node:20

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

# Install project-specific tools
RUN apt-get update && apt-get install -y \
    postgresql-client \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Pre-configure Claude Code settings directory
RUN mkdir -p /home/node/.claude

Reference it in devcontainer.json:

{
  "build": {
    "dockerfile": "Dockerfile"
  }
}

GitHub Codespaces

Codespaces provide cloud-hosted dev containers accessible from your browser or local VS Code.

Codespaces-Specific Configuration

{
  "name": "Codespace with Claude Code",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest",
  "secrets": {
    "ANTHROPIC_API_KEY": {
      "description": "API key for Claude Code",
      "documentationUrl": "https://console.anthropic.com/settings/keys"
    }
  },
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "openBrowser"
    }
  }
}

The secrets field prompts developers to configure their API key when creating the Codespace.

Note

In Codespaces, Claude Code runs in the terminal panel. Open a terminal with Ctrl+` and type claude to start. Your API key is automatically available from the Codespace secrets.

Sharing Claude Code Configuration

Mounting Local Config

Share your local Claude Code settings with the container:

{
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
  ]
}

This shares your sessions, auto-memory, and personal settings with the container. Changes in the container are reflected on your host.

Project-Level Configuration

Since .claude/settings.json, .claude/commands/, and .claude/agents/ are part of your repository, they are automatically available inside the container. No additional configuration needed.

Tip

Copy-paste devcontainer config with full Claude Code integration:

{
  "name": "Full Claude Code Setup",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postStartCommand": "npm install -g @anthropic-ai/claude-code@latest && npm install",
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
    "CLAUDE_CODE_USE_BEDROCK": "${localEnv:CLAUDE_CODE_USE_BEDROCK}",
    "AWS_PROFILE": "${localEnv:AWS_PROFILE}"
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.aws,target=/home/node/.aws,type=bind,readonly"
  ]
}

Security Considerations

API Key Handling

Never hardcode API keys in devcontainer.json. Use one of these approaches:

1. Environment variable passthrough: "${localEnv:ANTHROPIC_API_KEY}"
2. Codespace secrets: Configured per-user in GitHub settings
3. apiKeyHelper script: Generates keys dynamically from a secrets manager

Network Isolation

A custom Docker network plus a proxy env var is only a starting point — by itself it does not restrict egress, because nothing forces traffic through the proxy or blocks direct connections:

{
  "runArgs": ["--network=project-network"],
  "remoteEnv": {
    "HTTPS_PROXY": "http://proxy:8080"
  }
}

To actually isolate the network, use a default-deny firewall that whitelists only the domains Claude Code needs (the Anthropic API, your package registry, your VCS host). The official Claude Code reference devcontainer does exactly this — see init-firewall.sh, which blocks all outbound traffic by default and verifies the rules on container startup.

Tip

Start from the hardened reference implementation instead of rolling your own. Claude Code ships a security-hardened reference devcontainer with a default-deny firewall via init-firewall.sh. Because egress is locked down, it is safe to run claude --dangerously-skip-permissions inside it for unattended sessions — something you should never do on an unrestricted machine.

Sandbox Mode

Claude Code ships a native sandbox that uses OS-level primitives to restrict filesystem and network access for the bash tool — but it is opt-in, off until you turn it on, not enabled by default. There is no CLAUDE_CODE_SANDBOX environment variable; enabling it through remoteEnv does nothing.

Turn the sandbox on from inside Claude Code by running the /sandbox command, which opens a menu of sandbox modes (and prints install instructions if dependencies like bubblewrap or socat are missing on Linux):

> /sandbox

To make it the default for everyone who opens the container, configure it under the sandbox key in .claude/settings.json (committed to the repo). Inside a container the sandbox adds defense in depth on top of container isolation — the two are complementary, not redundant. See the sandboxing docs for the full settings reference.

Note

The reference devcontainer below takes a different, stronger approach to the same problem: instead of the per-command sandbox it wraps the whole container in a default-deny firewall, which is what makes unattended claude --dangerously-skip-permissions runs reasonable.

When This Breaks

Claude Code not found after container rebuild: The postStartCommand runs after every container start, but the postCreateCommand only runs on creation. Put Claude Code installation in postStartCommand to ensure it survives rebuilds.

Mounted .claude directory has wrong permissions: Container users may differ from your host user. Add a postStartCommand to fix permissions: "sudo chown -R node:node /home/node/.claude".

API key not available in container terminal: Make sure you are using ${localEnv:ANTHROPIC_API_KEY} (not ${containerEnv}). The localEnv prefix passes variables from your host machine.

Sessions from host do not appear in container: Sessions are stored by directory path. If the project path differs between host and container (e.g., /Users/you/project vs /workspaces/project), sessions will not match. This is expected behavior.

What is Next

• Enterprise Integration — Managed settings for container-based deployments
• GitHub Actions — CI/CD workflows that complement your dev container setup
• Proxy Configuration — Configure network access within containers