A minimal, secure container for running Claude Code locally with **any** container runtime.
Sign in to like and favorite skills
A minimal, secure container for running Claude Code locally with any container runtime.
The container works with any available runtime you have installed!
# Copy the example environment file cp .env-example .env # Edit .env with your information # Update GIT_USER_NAME and GIT_USER_EMAIL vim .env
# Install security tools and pre-commit hooks task setup-security # Scan for secrets (requires gitleaks installed) task scan-secrets
task build
docker run -it --rm -v $(pwd):/workspace claude-code:latest --help docker run -it --rm -v $(pwd):/workspace -v ~/.claude:/home/claude/.claude claude-code:latest init
🐳 With Docker:
docker run -it --rm -v $(pwd):/workspace -v ~/.claude:/home/claude/.claude claude-code:latest --help
🫙 With Podman:
podman run -it --rm -v $(pwd):/workspace -v ~/.claude:/home/claude/.claude claude-code:latest --help
This project uses Task for automation:
task --list # Show available tasks task check-versions # Check current component versions task update-dockerfile # Update to latest versions task build # Build the container image task setup-security # Setup security tools (one-time) task scan-secrets # Scan for secrets offline task check-security # Run all security checks task verify-no-secrets # Verify staged files before commit
This project includes offline security scanning with dual detection engines to prevent secrets and PII from being committed:
Tools Used:
Tool Comparison:
Setup (Required once):
# 1. Install gitleaks (choose your platform) # macOS: brew install gitleaks # Linux: wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.0/gitleaks_8.18.0_linux_x64.tar.gz tar -xzf gitleaks_8.18.0_linux_x64.tar.gz sudo mv gitleaks /usr/local/bin/ # 2. Install TruffleHog (optional, for comprehensive scanning) pip install trufflehog # or via task: task security:install-trufflehog # 3. Setup security tools and hooks task setup-security
Usage:
# Scan with Gitleaks (fast) task scan-secrets # Scan with TruffleHog (comprehensive with verification) task scan-secrets-trufflehog # Run all security checks (pre-commit + gitleaks + trufflehog) task check-security # Verify no secrets in staged files (gitleaks only) task verify-no-secrets # Verify with both scanners (comprehensive) task verify-all-secrets # Update secrets baseline (after reviewing findings) task update-secrets-baseline
Pre-commit Hooks: Once installed, these checks run automatically on
git commitBypass (Emergency only):
git commit --no-verify # Only use if absolutely necessary
~/.claude/.env.env-exampleThe project uses environment variables for sensitive configuration:
Setup:
# 1. Copy the example file cp .env-example .env # 2. Edit with your details vim .env
Environment Variables:
# Git Configuration (for container) GIT_USER_NAME=Your Name [email protected] # Docker Build Configuration USER_ID=1001 # Your user ID (run: id -u) GROUP_ID=1001 # Your group ID (run: id -g) CLAUDE_CODE_VERSION=2.0.36 # Claude Code version ALPINE_VERSION=3.21 # Alpine Linux version # Development tool versions TFLINT_VERSION=0.54.0 # Terraform linter HADOLINT_VERSION=2.12.0 # Dockerfile linter TERRASCAN_VERSION=1.19.8 # IaC security scanner TASK_VERSION=3.40.1 # Task runner
Security Note:
.env.env.gitignoreBase Image: Alpine Linux 3.21 Size: ~80MB (significantly smaller than Debian-based images) Package Manager: apk (Alpine Package Keeper)
Installed Tools:
. ├── Dockerfile # Multi-stage Alpine-based image with dev tools ├── Taskfile.yml # Main task configuration ├── TODO.md # Issue tracking and prioritized action plan ├── .env # Environment variables (git-ignored) ├── .env-example # Environment template (committed) ├── .gitignore # Git exclusions ├── .dockerignore # Docker build exclusions ├── .pre-commit-config.yaml # Pre-commit hooks configuration ├── .gitleaks.toml # Gitleaks scanner configuration ├── trufflehog.yaml # TruffleHog scanner configuration ├── .secrets.baseline # Detect-secrets baseline (auto-generated) ├── .taskfiles/ │ ├── VersionManagement.yml # Version management automation │ └── Security.yml # Modular security tasks ├── files/ │ └── gitconfig.template # Git config template (no PII) └── README.md # This file
For detailed issue tracking and project improvements, see TODO.md.
🚫 Permission issues: The container runs as your user, so file permissions should match your local environment.
🔑 API key issues: Make sure your Claude API key is configured in
~/.claude/💾 Memory issues: Add memory limits using
--memory=512m🔒 Pre-commit hook failures:
# If gitleaks is not found which gitleaks # Should return path, if not, install it # Skip hooks temporarily (emergency only) git commit --no-verify # Reinstall hooks pre-commit uninstall task setup-security
📧 False positive PII detections:
# Update the secrets baseline to exclude known false positives task update-secrets-baseline # Or edit .gitleaks.toml to add allowlist patterns
# Remove Docker/Podman images docker image rm claude-code:latest # Remove Docker image # or podman image rm claude-code:latest # Remove Podman image # Remove Claude configuration (if needed) rm -rf ~/.claude # Remove pre-commit hooks (if needed) pre-commit uninstall # Remove local environment file (keep .env-example) rm .env # Remove security baselines (will regenerate on next setup) rm .secrets.baseline