ai-pod runs Claude Code inside isolated containers (Podman or Docker) so your AI has exactly the tools it needs — and nothing it shouldn't touch.
curl -fsSL
https://raw.githubusercontent.com/mismosmi/ai-pod/main/install.sh
| bash
Each workspace gets its own container with full isolation, persistent state, and fine-grained host access — all managed automatically.
Every directory gets a dedicated container (Podman or Docker), named by a hash of its path. Projects can't interfere with each other.
A named volume preserves
~/.claude across sessions — your login,
memory, settings, and conversation history survive
container restarts.
Before mounting your workspace, ai-pod scans for secrets and credential files and prompts you to review or abort — keeping sensitive data out of the container.
Add an ai-pod.Dockerfile to any
project, starting from any base image. Node, Python,
Rust, Playwright — whatever your project needs.
Your host ~/.claude/settings.json and
CLAUDE.md
are merged with container defaults at launch, so
your personal Claude preferences follow you
everywhere.
The bundled host-tools binary lets
Claude run commands on the host machine. Every
command requires your explicit approval — with a
persistent allowlist for trusted ones.
When a Claude session ends, ai-pod sends a native desktop notification to the host so you know exactly when to come back.
Containers reach host services at
host.containers.internal (Podman) or
host.docker.internal (Docker), so
Claude can hit your local dev server, database, or
API without any manual port mapping.
ai-pod silently checks for new releases on startup and lets you know when there's a newer version available — no manual polling needed.
Claude can start long-running processes on the host — dev servers, file watchers, build pipelines — and track them by ID. Daemons are stopped automatically when the session ends.
Four steps. Two commands. One minute from install to your first session.
You'll need Podman or Docker already installed. Then grab ai-pod with the one-line install script at the top of this page.
cd into your project and run
ai-pod init. This drops an
ai-pod.Dockerfile in the workspace
that you can edit — pick your base image, install
the tools Claude should have, and add any MCP
servers. See the
example in Usage.
Run ai-pod. It scans the workspace
for credentials, builds the image, starts the
shared background server, and drops you into a
Claude Code session inside the container. The
first run takes a minute; later runs are instant
unless the Dockerfile changed.
Next time, just run ai-pod again from
the same directory. Use
ai-pod run claude resume to pick up
your last session, or ai-pod run bash
to poke around inside the container.
ai-pod handles container lifecycle, image building, server management, and credential checking automatically. You just run it.
The workspace is scanned for secrets before anything is mounted into a container.
Your ai-pod.Dockerfile is used to build
a project-specific image. Rebuilt only when the file
changes.
A lightweight background server starts on the host, bridging host-interaction requests from all containers.
Your workspace is mounted, settings are injected, and Claude Code starts inside the isolated container.
One command to launch. A handful more for everything else.
# Launch Claude in current directory ai-pod # Launch in a specific directory ai-pod --workdir /path/to/project # Force rebuild the container image ai-pod --rebuild # Resume the last Claude session ai-pod run claude resume # Open a shell in the container ai-pod run bash
# Create a custom Dockerfile ai-pod init # Build image without launching ai-pod build # List all Claude containers ai-pod list # Remove container for current workspace ai-pod clean # Skip credential scan ai-pod --no-credential-check
# Run a command on the host host-tools run-command ls ~/Desktop # Open a URL in the host browser host-tools run-command open https://example.com # List previously approved commands host-tools run-command --list # Send a desktop notification host-tools notify-user "Build finished"
# Start a background process, get its ID host-tools daemon start npm run dev → a3f91c820b4e # Stream its output (follows until exit) host-tools daemon output a3f91c820b4e # Check status and exit code host-tools daemon status a3f91c820b4e # List all daemons for this project host-tools daemon list # Stop one or all daemons host-tools daemon stop a3f91c820b4e host-tools daemon stop-all
# Start from any base image you need FROM node:22 # Add Playwright for browser testing RUN npx playwright install --with-deps # Install a project-specific MCP server RUN npm install -g @my-org/mcp-server
ai-pod is built around the assumption that you shouldn't have to fully trust the AI with your whole machine. Defense-in-depth, not just a checkbox.
Known issues and how to work around them. If you hit something that isn't here, open an issue on GitHub.
Your workspace is bind-mounted into the container
at /app. The claude user
inside the container has its own uid, and if that
uid doesn't line up with the host uid that owns
the files, Claude can't write to
/app — or new files end up with an
owner you can't edit on the host.
There are three independent knobs for fixing this. Pick the one that matches where you want the fix to live: per-project, per-run, or globally.
Pass -u <uid> to
useradd so the claude
user is built with a specific uid instead of the
distro default. Check your host uid first with
id -u. Most surgical fix — stays
inside the one project.
RUN useradd -u 1000 -ms /bin/bash claude \ && chown -R claude /app
PODMAN_USERNS globally
PODMAN_USERNS is a standard Podman
environment variable. When set, it becomes the
--userns value for every
podman run — including the ones
ai-pod makes. Use this to configure user namespace
mapping across every project.
export PODMAN_USERNS=keep-id:uid=1000,gid=1000
To see exactly where the mismatch is, compare the host view and the container view:
# On the host id -u # your host uid ls -ln ai-pod.Dockerfile # numeric owner of your files # Inside the container ai-pod run bash id # uid/gid of the claude user ls -ln /app # what the container sees as owner
If the uid from id inside the
container doesn't match the numeric owner of
/app, that's the gap — apply one of
the three fixes above.
Works on Linux and macOS. Requires Podman or Docker.
curl -fsSL
https://raw.githubusercontent.com/mismosmi/ai-pod/main/install.sh
| bash