Claude Code Safe

Run Claude Code in a sandboxed Docker container with network restrictions and skip-permission mode.

Why Use This?

• Security: Run Claude Code with dangerously-skip-permissions safely in an isolated container
• Network Restrictions: Firewall limits access to GitHub, npm, Anthropic API, and essential services only
• Zero-Friction: One command to install, one command to run - Claude starts automatically
• No Manual Setup: npm handles everything - no alias configuration needed
• Conflict Detection: Automatically checks for existing Claude Code installations
• Easy Setup: No API key required - login with your Claude.ai account
• Easy Updates: Simple npm update to get latest version
• Persistent Config: Authentication and history saved between sessions
• Cross-Platform: Works on Linux, macOS, and Windows (via WSL)

Requirements

• Node.js 14+ (for npm installation - recommended)
• Docker Engine 20.10+ (or Docker Desktop on Windows/macOS)
• Docker Compose 2.0+
• A Claude.ai account or Anthropic API key
• Windows only: WSL 2 with Docker Desktop WSL integration (setup guide)

Installation

npm Install (Recommended)

One command to install:

npm install -g claude-code-safe

The installer automatically:

• ✅ Checks for conflicts with official Claude Code
• ✅ Verifies Docker and Docker Compose are installed
• ✅ Builds the Docker image (first time only, 2-5 minutes)
• ✅ Makes the claude command available globally
• ✅ No manual alias configuration needed!

If official Claude Code is already installed, you'll see options to:

• Uninstall it first: npm uninstall -g @anthropic/claude-code
• Install locally instead: npm install claude-code-safe (use with npx claude)
• Continue anyway (not recommended - may cause conflicts)

Alternative: Manual Installation

If you don't have npm or prefer manual control:

git clone https://github.com/DanielKraehenbuehl/claude-safe.git
cd claude-safe
./setup.sh

Then create an alias in your shell config (~/.bashrc, ~/.zshrc, etc.):

alias claude='/path/to/claude-safe/claude-safe.sh'
source ~/.bashrc  # or ~/.zshrc

Quick Start

After installation, using Claude Code Safe is simple:

# Navigate to your project
cd /path/to/your/project

# Run Claude
claude

Or run on a specific directory from anywhere:

claude /path/to/your/project

First-Time Login: On first run, Claude shows an authentication URL. Copy it, open in your browser, login with your Claude.ai account, and authorize. Your authentication is saved for future sessions.

Claude Code starts automatically with --dangerously-skip-permissions enabled in a secure Docker container with network restrictions.

Commands

After npm installation, these commands are available:

# Run Claude Code on current directory
claude

# Run on specific directory
claude /path/to/project

# Show help
claude --help

# Show version
claude --version

# Manually rebuild Docker image (if needed)
claude-code-safe-setup

For manual installation, use:

./claude-safe.sh                    # Run on current directory
./claude-safe.sh /path/to/project   # Run on specific directory
./setup.sh                          # Rebuild Docker image
./setup.sh --force                  # Force rebuild (no cache)

Windows Setup

Claude Safe works on Windows via WSL (Windows Subsystem for Linux):

1. Install WSL 2:

   # In PowerShell (as Administrator)
   wsl --install

2. Install Docker Desktop for Windows:

   • Download from docker.com
   • Enable WSL 2 integration in Settings > Resources > WSL Integration

3. Install Node.js in WSL (if using npm):

   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt-get install -y nodejs

4. Install Claude Code Safe from WSL terminal (Ubuntu, Debian, etc.):

   npm install -g claude-code-safe

Access Windows projects via /mnt/c/ paths:

cd /mnt/c/Users/YourName/Documents/my-project
claude

For manual installation, use:

cd /mnt/c/Users/YourName/Documents/my-project
~/claude-safe/claude-safe.sh

Clipboard integration: Built-in copy and paste commands work with Windows clipboard:

echo "text" | copy    # Copy to Windows clipboard
paste                 # Paste from Windows clipboard

Known WSL issue: You may see input echo twice (cosmetic only, doesn't affect functionality).

How It Works

• Project directory automatically mounts at /workspace in the container
• Changes appear instantly on your host machine
• Authentication and history persist in Docker volumes (survive container restarts)
• Network firewall restricts outbound connections to approved domains
• Container runs as non-root user for additional security
• Each run creates a fresh container that auto-deletes on exit (type exit or Ctrl+D to stop)

Using get-shit-done Workflows

The container includes the get-shit-done (GSD) framework for structured, spec-driven development.

Why Use GSD?

• Structured Planning: Define requirements, create roadmaps, plan phases systematically
• Quality Consistency: Each task runs in a fresh context window
• Atomic Commits: Individual tasks produce separate git commits
• Parallel Execution: Run multiple agents concurrently
• Session Persistence: Project state persists across container restarts

Quick Start Workflow

cd ~/my-new-app
claude

# Inside Claude Code:
/gsd:new-project         # Extract project vision through guided questions
/gsd:define-requirements # Scope features across versions (MVP, v2, v3)
/gsd:create-roadmap      # Structure development into phases
/gsd:plan-phase          # Generate atomic task plan
/gsd:execute-phase       # Execute tasks with parallel agents
/gsd:verify-work         # Verify requirements met
/gsd:complete-milestone  # Ship version and prepare next

GSD maintains these files in your project:

• PROJECT.md - Project vision and overview
• REQUIREMENTS.md - Versioned feature requirements
• ROADMAP.md - Phase structure and task mapping
• STATE.md - Current execution state

Key Commands

Project Setup:

• /gsd:new-project - Extract project ideas through guided questioning
• /gsd:research-project - Investigate domain ecosystems and best practices
• /gsd:define-requirements - Scope features across versions
• /gsd:create-roadmap - Structure development phases
• /gsd:map-codebase - Analyze existing codebases

Execution:

• /gsd:plan-phase - Generate atomic task plans
• /gsd:execute-phase - Run parallel agents
• /gsd:execute-plan - Interactive single-plan execution
• /gsd:verify-work - Verify completed work
• /gsd:complete-milestone - Ship versions

Session Management:

• /gsd:pause-work - Save current state
• /gsd:resume-work - Resume from saved state

Type /gsd:help inside Claude Code for full command list.

Learn More

• GSD Repository: https://github.com/glittercowboy/get-shit-done
• Troubleshooting: See GSD troubleshooting below

Updating and Uninstalling

Update to Latest Version

If installed via npm:

# Update the package
npm update -g claude-code-safe

# The Docker image will be rebuilt automatically
# Or rebuild manually if needed
claude-code-safe-setup

If installed manually:

cd /path/to/claude-safe
git pull
./setup.sh

Uninstall

If installed via npm:

npm uninstall -g claude-code-safe

If installed manually, simply delete the directory:

rm -rf /path/to/claude-safe
# Remove alias from ~/.bashrc or ~/.zshrc

Advanced Usage

Local Installation (Project-Specific)

Install in a specific project without global access:

cd /path/to/your/project
npm install claude-code-safe
npx claude

This installs Claude Code Safe only for this project, with no global claude command.

Using an API Key

If you prefer API key authentication over web login:

For npm installation:

# Find installation directory
npm root -g

# Navigate to package directory (example for typical npm global path)
cd $(npm root -g)/claude-code-safe

# Create/edit .env file
echo "ANTHROPIC_API_KEY=your-key-here" >> .env

# Or edit the file directly
nano .env

For manual installation:

cd /path/to/claude-safe
echo "ANTHROPIC_API_KEY=your-key-here" >> .env

Then run claude as usual.

Read-Only Project Mount

Edit docker-compose.yml to mount projects in read-only mode:

For npm installation:

cd $(npm root -g)/claude-code-safe
nano docker-compose.yml

For manual installation:

cd /path/to/claude-safe
nano docker-compose.yml

Then change the volumes section to:

volumes:
  - ${PROJECT_DIR:-.}:/workspace:ro

Resource Limits

Add resource limits to docker-compose.yml:

Location: Same as above (npm: $(npm root -g)/claude-code-safe, manual: /path/to/claude-safe)

Add this to the service definition:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G

Direct Docker Compose

For npm installation:

cd $(npm root -g)/claude-code-safe
PROJECT_DIR=/path/to/project docker-compose run --rm claude-code

For manual installation:

cd /path/to/claude-safe
PROJECT_DIR=/path/to/project docker-compose run --rm claude-code

VS Code Dev Container

For full VS Code development environment inside the container, copy the included devcontainer.json to .devcontainer/ in your project, then use "Reopen in Container".

Customize Allowed Domains

The firewall allows these domains by default:

• GitHub (api.github.com, github.com, raw.githubusercontent.com)
• npm (registry.npmjs.org)
• Anthropic (api.anthropic.com, sentry.io, statsig.anthropic.com)
• Microsoft (packages.microsoft.com, marketplace.visualstudio.com)
• Python (pypi.org, files.pythonhosted.org)

To add custom domains:

For npm installation:

# Navigate to package directory
cd $(npm root -g)/claude-code-safe

# Edit init-firewall.sh around line 76
nano init-firewall.sh

# Add your domain to the list:
for domain in \
    "registry.npmjs.org" \
    "api.anthropic.com" \
    "your-custom-domain.com"; do

# Rebuild the image
claude-code-safe-setup

For manual installation:

cd /path/to/claude-safe
nano init-firewall.sh  # Add your domain
./setup.sh             # Rebuild

Configuration

The .env file is created automatically during installation with default values. To customize:

For npm installation:

# Navigate to package directory
cd $(npm root -g)/claude-code-safe

# Edit .env file
nano .env

For manual installation:

cd /path/to/claude-safe
cp .env.example .env  # If not exists
nano .env

Available options:

# Authentication (leave empty for web-based login, recommended)
ANTHROPIC_API_KEY=

# Optional: Your timezone (default: America/Los_Angeles)
TZ=America/New_York

# Optional: Claude Code version (default: latest)
CLAUDE_CODE_VERSION=latest

# Optional: Project directory (default: current directory)
PROJECT_DIR=/path/to/your/project

# Optional: GSD default model - sonnet, opus, or haiku (default: sonnet)
GSD_DEFAULT_MODEL=sonnet

Container Lifecycle

Image vs Container:

• Image = Template built during installation or by claude-code-safe-setup
• Container = Running instance created when you run claude

When to rebuild the image:

• ✅ First time installation (automatic with npm)
• ✅ After updating the package: npm update -g claude-code-safe
• ✅ After modifying Dockerfile or firewall rules
• ✅ Run manually: claude-code-safe-setup (npm) or ./setup.sh (manual)
• ❌ NOT needed before every run

What persists between runs:

• ✅ Authentication (Docker volume)
• ✅ Command history (Docker volume)
• ✅ Project files (mounted directory)
• ❌ Container itself (auto-deleted with --rm flag)

Troubleshooting

Installation Issues

npm install fails with "conflict detected":

If you see a conflict with official Claude Code:

# Option 1: Uninstall official Claude Code first
npm uninstall -g @anthropic/claude-code
npm install -g claude-code-safe

# Option 2: Install locally instead
npm install claude-code-safe
npx claude

"command not found: claude" after npm install:

Ensure npm global bin is in your PATH:

# Check where npm installs global packages
npm config get prefix

# Should be in your PATH (usually /usr/local or ~/.npm-global)
echo $PATH

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"

Docker image not built during install:

If Docker wasn't accessible during install, build manually:

claude-code-safe-setup

Code Colors/Syntax Highlighting Missing

Rebuild the container:

# If installed via npm
claude-code-safe-setup

# If installed manually
./setup.sh

Copy-Paste Not Working

WSL/Windows: Use Ctrl+Shift+C/Ctrl+Shift+V in Windows Terminal, or use the built-in copy/paste commands

macOS: Cmd+C/Cmd+V with mouse selection

Linux: Mouse selection auto-copies, Shift+Insert to paste

All platforms: Share via files:

echo "output" > /workspace/result.txt  # Inside container
cat /path/to/project/result.txt        # On host

Web Login Fails

Check port 38714 is exposed:

docker ps
# Should show: 0.0.0.0:38714->38714/tcp

Need to Re-authenticate

Delete the Docker volume storing credentials:

docker volume rm claude-code-config

Or if using docker-compose directly:

# Navigate to installation directory
cd $(npm root -g)/claude-code-safe  # npm install
# or
cd /path/to/claude-safe              # manual install

docker-compose down -v

Firewall Blocking Required Site

Test from inside container:

curl https://api.github.com  # Should work
curl https://google.com      # Should fail (blocked)

Add custom domains to init-firewall.sh and rebuild if needed.

get-shit-done Commands Not Found

Verify installation inside container:

# Inside Claude Code, type:
ls -la ~/.claude/commands/gsd/
# Should show 27 command files

If missing, rebuild the Docker image:

# If installed via npm
claude-code-safe-setup --force

# If installed manually
./setup.sh --force

Or install manually inside the container:

# Inside Claude Code, type:
npx --yes get-shit-done-cc --global

Requires Claude Code v0.7.0+ with skill support.

GSD State Not Persisting

Check volume exists:

docker volume ls  # Should show: claude-code-config

Verify project files:

ls /workspace/PROJECT.md

GSD Agents Slow

Increase resources in docker-compose.yml (see Resource Limits).

Check if agents need additional network domains in init-firewall.sh.

Permission Errors

The container runs as node user with passwordless sudo for package managers:

sudo apt-get install dotnet-sdk-8.0
sudo pip3 install robotframework
sudo npm install -g typescript

For full root access:

For npm installation:

cd $(npm root -g)/claude-code-safe
docker-compose run --rm --user root claude-code

For manual installation:

cd /path/to/claude-safe
docker-compose run --rm --user root claude-code

What's Included

• Node.js 20 with npm
• Python 3.11 with pip3
• Git with GitHub CLI (gh)
• Docker CLI with BuildX and Compose plugins
• Development tools: zsh, fzf, vim, nano, jq, wget, curl
• Network tools: iptables, ipset for firewall
• Claude Code (latest version)
• get-shit-done framework with slash commands
• pre-commit for git hooks
• Sudo access to package managers

Security Considerations

Even with Docker + firewall + skip permissions:

• ✅ Claude can modify/delete files in mounted project
• ✅ Claude can execute commands in the container
• ✅ Claude can consume resources (set limits if needed)
• ❌ Claude cannot access files outside mounted volumes
• ❌ Claude cannot install packages on your host
• ❌ Claude cannot access most internet sites (firewall restricted)

Files in This Repo

.
├── package.json            # npm package configuration
├── .npmignore              # npm publish configuration
├── bin/
│   ├── claude.js          # Main executable (installed as 'claude' command)
│   └── claude-setup.js    # Setup helper (installed as 'claude-code-safe-setup')
├── scripts/
│   ├── check-conflicts.js # Pre-install conflict detection
│   └── postinstall.js     # Post-install setup and Docker build
├── setup.sh               # One-command setup script
├── claude-safe.sh         # Run Claude safely in container
├── setup-clipboard.sh     # Clipboard integration setup
├── docker-compose.yml     # Docker orchestration
├── Dockerfile             # Container image definition
├── init-firewall.sh       # Network firewall script
├── start-claude.sh        # Container entrypoint
├── devcontainer.json      # VS Code Dev Container config
├── .env.example           # Environment variables template
├── .gitignore             # Git ignore rules
├── LICENSE                # MIT License
├── CONTRIBUTORS.md        # Author and contributors
└── README.md              # This file

Publishing to npm (Maintainers)

To publish a new version to npm:

# 1. Update version in package.json
npm version patch  # or minor, or major

# 2. Test locally
npm install -g .
claude --version

# 3. Publish to npm
npm publish

# 4. Push tags
git push --tags

Before publishing, ensure:

• All tests pass
• Docker image builds successfully
• Documentation is up to date
• Version number follows semantic versioning

Contributing

Issues and pull requests welcome! Please ensure:

• Scripts remain simple and portable
• Security features are preserved
• Documentation stays beginner-friendly
• Test npm installation locally before submitting PRs

Author

Daniel Krähenbühl - Hamilton Medical AG

Credits

Built from the official Claude Code .devcontainer setup by Anthropic.