claudio

Run Claude Code isolated in a podman container, one command per project.

Files

• Containerfile: the image (Debian slim + Claude Code).
• claudio.sh: builds, updates and runs the container.
• .claudio: template for per-project settings (plain bash).

Install

mkdir -p ~/claudio && cp Containerfile claudio.sh ~/claudio/
chmod +x ~/claudio/claudio.sh
echo 'alias claudio=~/claudio/claudio.sh' >> ~/.bashrc

Requires podman (rootless is fine).

Usage

cd ~/projects/myapp
claudio              # start Claude Code here (builds the image on first run)
claudio --resume     # any extra args are passed to claude
claudio shell        # bash inside the container instead of claude
claudio build        # build the image
claudio update       # rebuild from scratch: latest base image + latest Claude Code

The current directory is mounted at the same path inside the container. Nothing else from the host is visible unless you add it to a .claudio file.

Per-project settings

Copy the template into a project and uncomment what you need:

cp ~/claudio/.claudio ~/projects/myapp/

MOUNTS=("$HOME/.gitconfig:/home/claude/.gitconfig:ro" "/data/shared")
PODMAN_ARGS=(-e GITHUB_TOKEN -p 3000:3000)
CLAUDE_ARGS=(--model opus)

• MOUNTS: extra -v mounts. A bare path is mounted at the same path. Add :ro for read-only.
• PODMAN_ARGS: extra podman run options.
• CLAUDE_ARGS: default arguments for claude.

.claudio is sourced as bash, so only use ones you trust.

State

The container's home (/home/claude) lives in the podman volume claudio-home. This volume is shared by all projects and holds your login, settings and history. The container itself is removed after every run.

• Reset everything: podman volume rm claudio-home
• Need more tools in the image? Add them to the apt-get install line, then run claudio update.

Notes

• Files written in mounts are owned by your host user (--userns=keep-id).
• SELinux labeling is disabled for the container, so mounts work without relabeling.
• claudio refuses to run from $HOME or /.