ccpod

Imported from yorch/ccpod (AGENTS.md). Install upstream with npx skills add yorch/ccpod. Copyright stays with the author.

Project Guidelines

This file provides guidance to AI agents when working with code in this repository.

CLAUDE.md is a symlink to AGENTS.md — any changes here should be reflected in CLAUDE.md and vice versa.

Package manager

This project uses bun exclusively. Never use npm, pnpm, or yarn. Always run bun install, bun run <script>, bun test, etc. The website (website/) also uses bun — same rule applies there.

Commands

bun run dev              # run CLI without building
bun run build            # compile to dist/ccpod binary
bun run typecheck        # tsc --noEmit
bun run check            # biome format + lint (writes fixes)
bun test                 # all tests
bun test tests/unit/config/merger.test.ts  # single test file

Website commands

cd website
bun run dev              # start Astro dev server
bun run build            # build to website/dist/
bun run preview          # preview built site

Architecture

ccpod is a CLI that runs Claude Code in Docker. Entry point: src/cli/index.ts (citty router).

Config pipeline (the core flow)

ccpod run executes this pipeline in order:

1. Load — src/config/loader.ts reads ~/.ccpod/profiles/<name>/profile.yml (profile) and walks up from cwd to find .ccpod.yml (project). Both validated via Zod schemas in src/config/schema.ts.
2. Sync — src/profile/git-sync.ts pulls the profile's config repo if source: git.
3. Merge — src/config/merger.ts combines profile + project using merge: deep|override strategy. CLAUDE.md files are merged separately via mergeClaudes() (append or override).
4. Auth — src/auth/resolver.ts resolves API key or OAuth credentials into env vars. Same module's resolveEnvForwarding collapses profile/project/CLI env lists, supporting bare KEY (forward host var), KEY=value (literal), and KEY=${HOST_VAR} / KEY=${HOST_VAR:-default} (interpolation, scoped to env values only).
5. Config write — src/config/writer.ts writes merged config to a temp dir mounted as /ccpod/config in the container.
6. Container spec — src/container/builder.ts builds the ContainerSpec (binds, env, ports, labels, tmpfs). Exports computeProjectHash(dir).
7. Sidecars — src/container/sidecars.ts creates shared Docker network ccpod-net-<hash> and starts declared services: containers before the main container.
8. Run — src/container/runner.ts creates/reattaches/starts the container via docker CLI (Bun.spawn). TTY mode = interactive; headless mode (--file) streams logs.

Key modules

Storage layout

~/.ccpod/
  config.yml             # global ccpod settings (autoCheckUpdates, etc.)
  profiles/<name>/
    profile.yml          # profile config
    config/              # Claude config dir (if source: git, cloned here)
  credentials/<name>/    # auth tokens/keys
  state/<name>/          # persistent state (when state: persistent, stateIsolation: per-profile)
  state/<name>/<hash>/   # per-project state (when state: persistent, stateIsolation: per-project)
Docker volumes:
  ccpod-plugins-<profile>   # persistent plugin installs

Container mounts

• /workspace — project dir (rw)
• /ccpod/config — merged Claude config dir (ro)
• /ccpod/credentials — auth credentials (rw)
• /ccpod/plugins — named volume for plugins
• /ccpod/state — host bind ~/.ccpod/state/<profile>/ (persistent) or tmpfs (ephemeral)

Security invariants

• Profile names are validated by Zod regex /^[a-zA-Z0-9_-]{1,64}$/ — enforced at parse time in schema.ts and at the CLI entry point via validateProfileArg() (src/cli/validate.ts). Every command that accepts --profile calls validateProfileArg before passing the name to profileExists, getProfileDir, getStateDir, etc., preventing path traversal (../etc) and shell metacharacter injection through the profile name. The shared setup helper setupContainer also validates, covering run and shell.
• --file arg in run.ts is normalized and rejected if it starts with .. or is absolute.
• Config temp dirs live under a private per-uid parent ${tmpdir}/ccpod-u<uid> (created 0o700, verified owned by us and not a symlink), so another user on a shared host cannot pre-seed or race the deterministic per-content path. Dirs are 0o700, files 0o600, and the merged config is assembled in a mkdtemp dir then atomically renamed into place (a reader never sees a half-populated mount). On reuse, the writer lstats outDir and refuses it if it is a symlink, not a directory, or owned by a different uid.
• Per-profile directories — profilesDir(), credentialsBase(), and getStateDir() all mkdir with mode: 0o700, so another local user cannot read a profile's config, credentials, or Claude conversation state. The ~/.ccpod base dir itself is also created 0o700 by ensureCcpodDirs() and saveGlobalConfig(), with chmodSync to tighten pre-existing dirs that may have been created with looser perms by prior versions.
• .mcp.json is parsed through a Zod schema (src/mcp/parser.ts): the server map is capped at 64 entries, auto-exposed HTTP/SSE ports must be in 1–65535, and both JSON-parse and schema-validation failures are surfaced via console.warn rather than silently swallowed. Symlinked .mcp.json files are rejected via lstatSync — an untrusted project could otherwise point .mcp.json at an arbitrary host file (e.g. /etc/shadow) to probe readability. The same symlink rejection applies to .ccpod.yml in findProjectConfig (protecting all callers, including config validate).
• Resolved credential + forwarded env are passed to the container as bare -e KEY flags with the values injected into the docker CLI's own environment (ContainerSpec.secretEnv → dockerSpawn extraEnv), never as -e KEY=VALUE argv — so secrets don't appear in ps / /proc/<pid>/cmdline. ccpod's own CCPOD_* control vars stay as plain flags.
• Restricted network (docker/entrypoint.sh) fails closed: if iptables is missing or any load-bearing rule (loopback, established, default-deny) cannot be installed, the container aborts rather than run with unrestricted egress. IPv6 is locked down via ip6tables (fail-closed when the kernel has IPv6 but ip6tables is absent), and DNS is scoped to /etc/resolv.conf nameservers instead of an open :53.
• SSH_AUTH_SOCK is rejected if it contains : (would corrupt Docker bind spec).
• DOCKER_SOCKET_PATH env var overrides the hardcoded /var/run/docker.sock path (useful in tests and non-standard Docker setups).
• Profile config.repo must use https://, http://, ssh://, git://, or scp-style (user@host:path). config.ref rejects values starting with -, containing .., or carrying shell metacharacters — closes git option-injection (--upload-pack=...) RCE.
• auth.keyFile must point inside ~/.ccpod/ (typically ~/.ccpod/credentials/<profile>/...). At read time the resolver realpathSync-es the path and rejects it if the symlink target escapes ~/.ccpod/ — schema validation alone is a string-prefix check and would otherwise let a symlink under ~/.ccpod/ redirect to /etc/shadow. Use keyEnv to load keys stored elsewhere.
• Proxy auth mode (auth.type: proxy) eliminates the OAuth refresh-token rotation race between concurrent ccpod containers. Instead of copying .credentials.json into each container (which creates independent stores of the same rotating refresh token), ccpod starts a local HTTP proxy (src/auth/proxy.ts) before the container. The container runs claude in API-key mode with a format-valid sentinel key ([REDACTED openai-key]-...) and ANTHROPIC_BASE_URL pointing at the proxy. The proxy validates the sentinel, strips the x-api-key header, adds Authorization: Bearer <real-oauth-access-token>, and forwards to api.anthropic.com. The proxy holds the only OAuth session, refreshes the access token with a single-flight lock (proactively before expiry and on-demand on 401), and writes refreshed tokens back to the host Keychain. No .credentials.json enters the container, no credential mount is created, and the entrypoint skips credential copy-in/copy-out. Multiple containers share one proxy, which serializes refreshes and serves all consumers from one cache. Limitation: if native claude runs concurrently on the host and refreshes the same OAuth session independently, it can invalidate the proxy's refresh token. The proxy re-reads the host credential store on invalid_grant to recover, but a brief window of 401s is possible. On macOS the proxy binds to 127.0.0.1 (Docker Desktop routes host.docker.internal to host loopback); on Linux it binds to 0.0.0.0 (the sentinel key gates access) because host-gateway resolves to the bridge IP, not loopback.
• profile install prompts for confirmation on git and url sources before fetching; pass --yes to bypass. detectSource (src/profile/installer.ts) classifies scp-style user@host:path URLs as git (matching gitRepoSchema in schema.ts), so they are not misinterpreted as base64 data.
• Project config walk (findProjectConfig in src/config/loader.ts) stops at the user's home directory — a .ccpod.yml found above $HOME (e.g. at / on macOS) is not loaded, preventing a stray parent config from overriding profile settings for every child project.
• Updater (ccpod update) verifies the downloaded binary's SHA-256 against SHASUMS256.txt from the release; releases without that asset are refused. The install.sh bootstrap performs the same verification (aborting on mismatch; warning and proceeding only when the release predates the checksum asset).
• Project .ccpod.yml trust boundary — a repo's project config is untrusted by default:
  • services: project-declared sidecar services are ignored unless the profile sets allowProjectServices: true. A cloned repo could otherwise start arbitrary container images on the same bridge network as the credential-bearing main container. When opted in, services[].volumes and services[].ports are still sanitized (see below) unless allowProjectHostMounts is also set.
  • services[].volumes: host-path mounts rejected; only named volumes allowed unless the profile sets allowProjectHostMounts: true.
  • services[].ports: 0.0.0.0: and non-localhost binds rejected; two-part host:container is auto-localized to 127.0.0.1:. Bracketed IPv6 is recognised — [::1]:host:container loopback is accepted, every ::-expanding wildcard ([::], [0::], [::0:0], [0:0:0:0:0:0:0:0], …) is rejected.
  • top-level ports.list (main container) and auto-detected .mcp.json ports from project are published on 127.0.0.1 only, not 0.0.0.0 — parsePorts tags project-sourced mappings with hostIp: '127.0.0.1' (profile-sourced ports keep Docker's default bind). Prevents a cloned repo from exposing the credential-mounted container to the LAN.
  • env entries from project may not use ${VAR} interpolation (would exfiltrate host secrets), and may not set keys on PROJECT_ENV_DENYLIST (src/auth/resolver.ts) — the Anthropic credential/endpoint vars (ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_*_BASE_URL), proxy vars (HTTP(S)_PROXY / ALL_PROXY / NO_PROXY), NODE_OPTIONS (code injection), and TLS-trust vars (NODE_EXTRA_CA_CERTS / NODE_TLS_REJECT_UNAUTHORIZED / SSL_CERT_FILE / SSL_CERT_DIR / CURL_CA_BUNDLE / REQUESTS_CA_BUNDLE). These could redirect API traffic to exfiltrate the resolved credential, inject code into the credential-bearing process, or weaken TLS. Matched case-insensitively; ignored with a warning. Profile and --env entries are trusted and may set them. Project env entries with CCPOD_* or DOCKER_* prefixes are also blocked — CCPOD_* could override ccpod's own control vars (e.g. CCPOD_NETWORK_POLICY), and DOCKER_* (e.g. DOCKER_HOST) could redirect the docker CLI itself to an attacker-controlled daemon. builder.ts additionally strips CCPOD_* and DOCKER_* from secretEnv as defense-in-depth.
  • network: (policy and allow) is profile-owned — project network keys are ignored with a warning regardless of merge strategy, so a repo cannot downgrade a restricted profile to full or widen the allow-list.
  • init: commands are ignored unless the profile sets allowProjectInit: true.
• Project .claude/settings.json deep-merges into profile settings (project wins on conflicts) — same trust level as claudeArgs passthrough. Only run ccpod against repos you control.
• setupContainer (src/cli/commands/_setup.ts) throws on error instead of calling process.exit — the calling commands (run, shell) catch and exit. This makes the setup pipeline testable with await expect(...).rejects.toThrow(...). The global unhandledRejection/uncaughtException handler in cli/index.ts remains as a last-resort backstop.
• ccpod prune removes stopped ccpod containers, orphaned ccpod-net-* networks (no attached endpoints), unreferenced ccpod-plugins-<profile> volumes (no container references and profile no longer exists on disk), and orphaned per-project state dirs (no remaining containers with matching project hash). Supports --dry-run, --profile, and --force. Volume and state dir removal prompts for confirmation unless --force is given.
• stateIsolation (profile config, default per-profile) controls whether persistent state is shared across projects using the same profile (per-profile: ~/.ccpod/state/<profile>/) or isolated per project (per-project: ~/.ccpod/state/<profile>/<projectHash>/). When per-project, each project gets its own conversation history, todos, and statsig state — preventing cross-project state leakage when using the same profile for trusted and untrusted repos. ccpod state clear clears the current project's state by default; --all clears all state for the profile. ccpod prune cleans orphaned per-project state dirs.

Testing

Tests live in tests/unit/ and tests/integration/. Unit tests use bun:test; mock.module() is used for Docker subprocess isolation in container tests.

Workflow

• Always work in a dedicated worktree (e.g. git worktree add -b <branch> /path/to/ccpod-<branch> origin/main) unless the user explicitly says otherwise. Never commit directly to main.
• Open a PR for every change — no matter how small. Push the branch and use gh pr create with a clear title and description. Do not push directly to main.
• Clean up worktrees and local branches after the PR is merged.

Commit Checklist

Before every commit:

1. Quality gates — bun run typecheck && bun test tests/unit/ && bun run check must all pass
2. Docs — update CLAUDE.md, website/src/content/docs/reference/internals.md, or any affected docs to reflect the change
3. Code review — spawn a fresh subagent (the harness's built-in code reviewer, e.g. code-reviewer or general-purpose) to review the diff against the rest of the codebase; address any real bugs or meaningful risks before committing

Commit messages must follow Conventional Commits:

<type>(<scope>): <summary>

<body>

Types: feat, fix, refactor, test, docs, chore, perf, ci

Example: feat(state): replace Docker volume with host bind mount