Quick Start

This guide gets you from a fresh install to an interactive Claude session in your project.

1. Run the wizard

ccpod init

The wizard:

• Detects your container runtime (Docker / OrbStack / Colima / Podman)
• Asks for your auth method (API key or OAuth)
• Creates a default profile at ~/.ccpod/profiles/default/profile.yml

The base image is pulled automatically on first ccpod run.

You can re-run ccpod init later to add another profile.

2. Start a session

cd path/to/your/project
ccpod run

The current directory is mounted at /workspace inside the container. Claude starts there. Exit the session and the container shuts down (state is wiped unless your profile sets state: persistent).

Tip: If you skip ccpod init, running ccpod run from any directory automatically launches the wizard when no default profile exists.

3. Use a different profile

ccpod run --profile team

Or pin a profile to a project by adding .ccpod.yml:

.ccpod.yml

profile: team

ccpod walks up from $PWD to find this file, so any subdirectory of the repo works.

4. Headless mode

Pipe a prompt file and exit with the container’s status code:

ccpod run --file prompt.txt

Useful in CI for “review this diff” or “summarize these docs” automations.

What’s next

• Profiles — the unit of portability.
• Project config — overlay a profile per repo.
• State persistence — keep history between sessions.
• CLI reference — every command and flag.