ccpod

Run Claude Code in Docker. Portable, composable profiles for your Claude environment.

What is ccpod?

ccpod is an open-source (MIT) command-line tool that runs Claude Code inside a Docker container, with the whole Claude environment described by a portable profile. It runs on macOS and Linux (x86_64 and arm64) with Docker, OrbStack, Colima, or Podman.

Your Claude environment — settings, plugins, skills, CLAUDE.md, MCP servers — is usually pinned to one machine. ccpod wraps it in a profile: a versioned, portable config that travels with you, your team, or your open-source project. Every ccpod run drops you into a clean, reproducible Claude session inside a container.

Who is ccpod for?

Developers on more than one machine who want one source of truth for their Claude setup.
Teams that want a shared CLAUDE.md, settings, and plugin set, synced daily from a git repo.
Open-source maintainers who want to ship a known-good Claude environment to contributors.
Anyone working with untrusted code or sensitive data who wants Claude confined to a container, optionally with an outbound network allow-list.

Portable profiles

A profile bundles your Claude config, plugins, CLAUDE.md, MCPs, and image into a single versionable unit.

Reproducible sessions

Every ccpod run boots a clean container from a pinned image — no drift between machines or teammates.

Project-level overrides

.ccpod.yml sits in your repo and merges with the profile: deep-merge settings, append CLAUDE.md, add sidecars.

Sidecar services

Declare a Postgres, Redis, or queue alongside Claude. ccpod wires them onto a shared network automatically.

MCP auto-detection

HTTP/SSE MCP servers from .mcp.json are exposed without manual port flags.

Runtime-agnostic

Works with Docker, OrbStack, Colima, and Podman. ccpod auto-detects the socket.

Secure by default

Running an AI agent against a repo you did not write is a trust problem, so ccpod treats a project’s .ccpod.yml as untrusted:

Restricted network mode. Set network.policy: restricted and the container can only reach the hosts you allow-list. If the firewall rules cannot be installed, the container refuses to start rather than run open. See Network Policy.
Project config cannot escalate. A cloned repo cannot start sidecar containers or run init commands unless your profile opts in, and it can never widen the network allow-list or override your Anthropic credentials and proxy settings.
Secrets stay out of process lists. Credentials reach the container through the environment rather than command-line arguments, so they do not show up in ps.
No shared refresh-token race. With auth.type: proxy, a local proxy holds the only OAuth session, so several containers can run at once without invalidating each other’s login. See the auth proxy design.

See it in action

Why ccpod vs. plain Claude Code?

Feature	Bare Claude Code	ccpod
Portable config across machines	Per-machine ~/.claude only	Built into profile
Versioned via git	Manual sync	config: source: git
Reproducible base image	Drift between teammates	Pinned image tag
Network policy	Trusts host network	full or restricted allow-list
Untrusted repo config	Runs directly on your host	Project config treated as untrusted; risky keys need profile opt-in or are blocked
Sidecar services (DBs, queues)	docker compose alongside	Declared in profile.yml
MCP port forwarding	Manual port flags	Auto-detected from .mcp.json
Plugin install	Per-machine	Volume per profile, delta-installed
Auth handling	Files in ~/.claude	Profile-scoped credentials dir

30-second taste

# Install
curl -fsSL https://ccpod.brnby.com/install.sh | sh

# First-run wizard: detect runtime, set up auth, create default profile
ccpod init

# Drop into Claude in the current directory
ccpod run

Want to share an environment with your team? Point a profile at a git repo and everyone gets the same CLAUDE.md, settings, and plugin set — synced daily.

config:
  source: git
  repo: https://github.com/your-org/claude-config
  sync: daily

ccpod is released on GitHub: see the latest release and changelog.

Where to next

Quick start — install, init, run.
Profiles — the unit of portability.
Project config — overlay a profile per repo.
CLI reference — every command and flag.
Architecture — how the pipeline works.
Run on untrusted repos — a locked-down sandbox profile.
Migrate your ~/.claude — turn an existing setup into a profile.
Network policy — lock down outbound traffic.
Shared team profile — one config for the whole team.