🤖 Claude Code Container (Runtime Agnostic)

A minimal, secure container for running Claude Code locally with any container runtime.

✨ Features

• 🐋 Runtime Agnostic: Works with Docker, Podman, or Lillipod
• 🔒 Secure: Non-root user, read-only filesystem, network isolation
• 🚀 Simple: One command setup and execution
• 📁 Mount-friendly: Designed for volume mounting and local development
• 🏔️ Minimal: Based on Alpine Linux (~80MB) with comprehensive dev tools
• 🛠️ Dev-Ready: Pre-installed linting and IaC tools (tflint, hadolint, terrascan, shellcheck, yamllint, eslint, prettier, markdownlint, ansible, opentofu, task)

🛠️ Supported Container Runtimes

• 🐳 Docker - Traditional container runtime
• 🫙 Podman - Daemonless, rootless containers
• 🔹 Lillipod - Lightweight container runtime

The container works with any available runtime you have installed!

🚀 Quick Start

1. ⚙️ Environment Setup:

# Copy the example environment file
cp .env-example .env

# Edit .env with your information
# Update GIT_USER_NAME and GIT_USER_EMAIL
vim .env

2. 🔒 Security Setup (Recommended):

# Install security tools and pre-commit hooks
task setup-security

# Scan for secrets (requires gitleaks installed)
task scan-secrets

3. 🔨 Build the container:

task build

4. ▶️ Run Claude Code:

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

🏃 Runtime Usage

🐳 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

🛠️ Development Tasks

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

🔐 Security Features

• 👤 Runs as your user (UID/GID mapping)
• 📖 Read-only container filesystem
• 📂 Workspace can be mounted to your current directory
• ⚡ Minimal capabilities
• 🗂️ Temporary filesystem for /tmp
• 🔒 No secrets hardcoded in repository
• 🛡️ Pre-commit hooks for secret detection
• 🔍 Offline secret scanning with gitleaks

Secret Scanning & PII Protection

This project includes offline security scanning with dual detection engines to prevent secrets and PII from being committed:

Tools Used:

• gitleaks - Fast regex-based secret scanner (primary pre-commit tool)
• trufflehog - Entropy-based scanner with secret verification (comprehensive scanning)
• detect-secrets - Baseline-based secret detection
• pre-commit - Automated git hooks

Tool Comparison:

• Gitleaks: Fast, pattern-based, ideal for pre-commit hooks
• TruffleHog: Slower but more thorough with verification, best for test/verification steps

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 commit:

• ✅ Gitleaks secret scanning
• ✅ Email/PII detection
• ✅ Prevent committing .env files
• ✅ Detect private keys
• ✅ Check for common secret patterns

Bypass (Emergency only):

git commit --no-verify  # Only use if absolutely necessary

📋 Requirements

• 🛠️ One of: Docker, Podman, or Lillipod
• 🔑 Your Claude API key in ~/.claude/
• 📝 Configured .env file (copy from .env-example)
• 🔒 Optional: gitleaks for secret scanning
• 🐍 Optional: Python 3 + pip for pre-commit hooks

⚙️ Environment Configuration

The 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
GIT_USER_EMAIL=[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:

• ⚠️ Never commit .env to version control
• ✅ .env is already in .gitignore
• ✅ Pre-commit hooks prevent accidental commits

📦 Container Details

Base Image: Alpine Linux 3.21 Size: ~80MB (significantly smaller than Debian-based images) Package Manager: apk (Alpine Package Keeper)

Installed Tools:

• System: age, bash, curl, git, openssh, wget, httpie, jq, yq, tree, less
• Python: python3, pip, uv, azure-cli
• Node.js: nodejs, npm, claude-code, eslint, prettier, markdownlint-cli
• IaC/DevOps: ansible, opentofu, terraform/tofu, task, act, sops
• Security: trivy, terrascan, dive
• Linters: shellcheck, shfmt, yamllint, tflint, hadolint

📁 File Structure

.
├── 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.

🔧 Troubleshooting

🚫 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 flag if needed.

🔒 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

🧹 Cleanup

# 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