Dev Container Template

Reusable devcontainer for AI-assisted development with Claude Code. Python 3.13, Node.js 22, automatic macOS Keychain auth forwarding, and safety guardrails.

What's included

File	Purpose
Dockerfile	Python 3.13 + Node 22 + Playwright deps + uv
devcontainer.json	16GB memory limit, Claude config mounts, git identity
extract-claude-auth.sh	Extracts Claude Code OAuth tokens from macOS Keychain
post-create.sh	Installs Claude Code + project setup (customize per repo)
post-start.sh	Forwards credentials + symlinks host paths on every start
claude-dev.sh	Launches Claude Code with --dangerously-skip-permissions + safety rules
guardrail-hook.sh	Blocks secret reads, host config writes, git push from container

Quick start

1. Copy into your project

cp -r .devcontainer/ /path/to/your-project/.devcontainer/

2. Customize post-create.sh

Open .devcontainer/post-create.sh and uncomment the sections relevant to your project:

Python project:

uv sync --extra dev
uv tool install --editable --force "$REPO"

Node.js project:

npm ci --prefix "$REPO"

Frontend with separate directory:

sudo chown vscode:vscode "$REPO/frontend/node_modules"
npm ci --prefix "$REPO/frontend"
npm run build --prefix "$REPO/frontend"

3. Add project-specific mounts (optional)

Edit devcontainer.json to add bind mounts for data directories your project needs:

"mounts": [
    // ... existing mounts ...
    "source=${localEnv:HOME}/my-data,target=/workspace/data,type=bind,consistency=cached"
]

4. Open in VS Code

Cmd+Shift+P → "Dev Containers: Reopen in Container"

Prerequisites

• Docker runtime: OrbStack (recommended for Mac) or Docker Desktop
• Claude Code: Must be logged in on the host first (claude in terminal)
• OrbStack memory: Set to 16GB+ in OrbStack Settings → System → Memory limit

Using Claude Code inside the container

Two ways to launch:

claude          # Normal permissions — prompts for tool approval
claude-dev      # Skip permissions + safety guardrails (for trusted repos)

claude-dev enables frictionless development while blocking:

• Reading credential/secret files
• Modifying host Claude config (bind-mounted)
• git push (no SSH keys in container — push from host)

How auth works

1. Before container starts (initializeCommand): extract-claude-auth.sh reads your Claude Code OAuth tokens from macOS Keychain and writes them to ~/.config/devcontainer-auth/claude-oauth.json
2. On every container start (postStartCommand): post-start.sh copies those tokens into the container's ~/.claude/.credentials.json
3. No browser login needed inside the container

If you see a macOS Keychain access prompt, that's the extraction script — safe to allow.

Memory

The container is configured with a hard 16GB memory limit and no swap (--memory=16g --memory-swap=16g). This prevents OOM kills during parallel Claude Code agent execution.

Adjust in devcontainer.json → runArgs if your machine has more/less RAM. Leave ~8GB for macOS.

Adding guardrail hooks

guardrail-hook.sh is a PreToolUse hook template. To activate it, add to your Claude Code settings (inside container):

{
  "hooks": {
    "PreToolUse": [
      { "command": "/workspace/.devcontainer/guardrail-hook.sh" }
    ]
  }
}

Or extend it with project-specific rules (e.g., blocking writes to a bind-mounted data directory).

Customizing for your team

• VS Code extensions: Add to devcontainer.json → customizations.vscode.extensions
• Environment variables: Add "containerEnv" block or use --env-file in runArgs
• Named volumes: Use for directories that need Linux-specific binaries (e.g., node_modules)