Claude Code in Podman

Run Claude Code CLI inside a Podman container with GitHub access, persistent configuration, and a tmux session that lets you switch between Claude and a regular terminal.

Why?

Claude Code runs as a full CLI agent that can read, edit, and execute code in your project. Running it inside a container provides isolation — Claude operates in a sandboxed environment rather than directly on your host system.

The container includes tmux so you can open a shell alongside Claude (e.g. to run tests, inspect files, or use git) without leaving the container.

What's in the box

Prerequisites

• Podman installed
• Python 3.10+
• A Claude Code account (you'll authenticate on first run)
• An SSH key for GitHub access (optional)

Quick start

Run from PyPI (no clone needed)

uvx claude-podman \
    --workspace ~/my-project \
    --github-key ~/.ssh/id_ed25519 \
    --claude-config ./claude-auth

Run directly from GitHub (no clone needed)

Not recommended - better check what you are running first!

uvx --from git+https://github.com/serge-m/claude-podman claude-podman \
    --workspace ~/my-project \
    --github-key ~/.ssh/id_ed25519 \
    --claude-config ./claude-auth

Run from a local clone

git clone https://github.com/serge-m/claude-podman.git
cd claude-podman
uv run claude-podman \
    --workspace ~/my-project \
    --github-key ~/.ssh/id_ed25519 \
    --claude-config ./claude-auth

Arguments

Using tmux inside the container

Claude starts in a tmux session. Standard tmux keybindings apply:

What's installed in the container

GitHub's SSH host keys are pre-populated at build time via ssh-keyscan, so git operations won't prompt for host verification.

How it works

1. claude-podman resolves all paths, reads your git identity from the host, extracts the bundled Dockerfile from the package, builds the container image, and runs it with the appropriate volume mounts.
2. entrypoint.sh launches Claude inside a tmux session.
3. Your workspace is bind-mounted into the container, so changes Claude makes are reflected on your host filesystem immediately.

Persistent config

The --claude-config directory stores Claude's authentication and session data. Point this at the same directory across runs to avoid re-authenticating each time. A .claude.json file is automatically created inside it if missing.

Note: The config directory contains auth credentials. Don't commit it to version control.