Sandboxed Claude

Sandboxed Claude

Create a Podman dev container where Claude Code runs inside a controlled, reproducible environment. The container bind-mounts the project source, caches dependencies in named volumes, and persists Claude's own configuration across restarts. One script launches the whole thing.

See reference.md for annotated Containerfile and dev.sh templates.

Why Sandbox

Running Claude Code inside a container gives you three things:

1. Reproducibility. Every collaborator gets the same toolchain -- same Node, same JDK, same Maven -- without polluting their host. No "works on my machine."
2. Isolation. Claude operates within the container's filesystem boundaries. It can read and write the project (bind-mounted) but nothing else on the host.
3. Speed. Named Podman volumes store dependency trees (node_modules, .m2/repository) as Linux-native filesystems, avoiding the overhead of macOS filesystem translation on every file read.

The Two-File Pattern

Every sandboxed-claude setup produces exactly two files:

infra/devcontainer/
├── Containerfile   # Image definition: base + runtimes + tools + non-root user
└── dev.sh          # Launch script: volumes, mounts, container lifecycle

The Containerfile builds once and is reused. dev.sh handles everything else: creating volumes, building the image on first run, tearing down stale containers, and starting a fresh interactive session.

Workflow

1. Detect the Tech Stack

Read the project to identify what runtimes and tools are needed:

Most projects need one or two runtimes. A fullstack app typically needs Node + a backend runtime.

2. Choose the Base Image

Pick the base that gives you the most for free:

Use -bookworm (Debian 12) variants. They have apt-get for installing additional tools. Alpine images are smaller but cause friction with native dependencies and missing shared libraries.

3. Write the Containerfile

The Containerfile follows a fixed structure. Each section has a clear purpose:

Base image (primary runtime)
  → System dependencies (curl, git, ssh, ca-certificates, jq)
  → Secondary runtimes (JDK, Maven, etc.)
  → CLI tools (Angular CLI, Claude Code)
  → Non-root user setup
  → Working directory + config directories

Principles:

• Pin versions. Use build ARGs for runtime versions so they're visible and changeable at the top of the file. Pin CLI tools to the version matching the project.
• Clean apt caches. End every apt-get install with && rm -rf /var/lib/apt/lists/* to keep the image small.
• Non-root user. Create a dev user and switch to it before setting up workspace directories. Claude Code should never run as root inside the container.
• Prepare mount points. Create /home/dev/.claude and /home/dev/.ssh (if needed) with correct permissions before the user runs anything.

4. Write dev.sh

dev.sh is the single entry point. It handles the full container lifecycle:

#!/usr/bin/env bash
set -euo pipefail

The script does five things in order:

1. Resolve paths. Compute PROJECT_ROOT relative to the script location so it works from any working directory.
2. Create named volumes. Use podman volume exists || podman volume create for each dependency cache. Named volumes are Linux-native filesystems inside the Podman VM -- they bypass macOS filesystem translation entirely.
3. Build the image. Only if it doesn't already exist (podman image exists). Rebuilding is explicit: the user deletes the image when they want a fresh build.
4. Remove stale container. podman rm -f the previous container if it exists. Containers are ephemeral; volumes persist the state that matters.
5. Launch. podman run -it with all mounts and flags.

5. Configure Mounts and Volumes

This is where the decisions matter. There are three categories:

Bind mounts (source code):

-v "$PROJECT_ROOT:/workspace:z"

The entire project tree, read-write. The :z suffix is required for SELinux relabeling on Podman (harmless on systems without SELinux).

Named volumes (dependency caches):

-v "myproject-node-modules:/workspace/app/node_modules:z"
-v "myproject-m2-repo:/home/dev/.m2/repository:z"

Each dependency tree gets its own named volume. This serves two purposes: dependencies install fast (native filesystem, not macOS FUSE), and they persist across container restarts without re-downloading.

Mount the volume at the exact path where the package manager writes dependencies:

• npm/pnpm: <project>/node_modules
• Maven: ~/.m2/repository
• Gradle: ~/.gradle/caches
• Go: /home/dev/go/pkg/mod
• Cargo: /home/dev/.cargo/registry
• pip: varies (use a venv path)

Claude config (persistence):

-v "$HOME/.claude-container/myproject:/home/dev/.claude:z"

Store Claude's auth tokens, settings, and conversation history in a host directory. This survives container rebuilds. Keep it per-project under ~/.claude-container/ so different projects don't collide.

6. Essential Flags

podman run -it \
    --name myproject-dev \
    --hostname myproject-dev \
    --userns keep-id \
    ...

• --userns keep-id: Maps the container's dev user to your host UID. Without this, files created inside the container are owned by a different UID on the host, causing permission headaches. Required on macOS.
• --hostname: Sets a recognizable prompt inside the container.
• --name: Allows podman rm -f by name on next launch.

7. Optional: SSH Key Mounting

If the project deploys via SSH or needs git access over SSH:

-v "$HOME/.ssh/id_ed25519_myproject:/home/dev/.ssh/id_ed25519:ro,z"
-e "SSH_KEY=/home/dev/.ssh/id_ed25519"

Mount the key read-only (:ro). If the project deploys through CI/CD (GitHub Actions, etc.), skip this entirely.

8. Print First-Run Instructions

dev.sh should print what the user needs to do on first launch:

First run: execute inside the container:
  cd /workspace/app && npm ci
  cd /workspace/services && mvn dependency:go-offline
  claude auth login

These commands populate the named volumes. After the first run, subsequent launches are instant.

Adaptation Checklist

When creating a sandboxed-claude setup for a new project:

• Read package.json / pom.xml / go.mod to identify runtimes and versions
• Choose base image matching the primary runtime
• Pin CLI tool versions to match the project (e.g., Angular CLI from devDependencies)
• Create one named volume per dependency cache
• Mount node_modules at the exact path (watch for monorepo structures)
• Set --userns keep-id for macOS compatibility
• Include claude auth login in first-run instructions
• Test: build the image, launch, run npm ci / mvn compile, verify Claude Code works

What This Skill Does Not Cover

• Production containers. This skill is about dev environments. Production Dockerfiles are multi-stage builds optimized for size; dev containers are optimized for tooling.
• Docker Compose for services. If the project needs a database or message broker alongside the dev container, that's a separate compose file. The dev container is for the human (and Claude) to write code in.
• VS Code devcontainers. The .devcontainer/devcontainer.json format is IDE-specific. This skill produces standalone Podman containers that work from any terminal.