If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/containers/podman shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 18 active contributors
• Distributed ownership (top contributor 22% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live containers/podman repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/containers/podman.

What it runs against: a local clone of containers/podman — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in containers/podman | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of containers/podman. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/containers/podman.git
#   cd podman
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of containers/podman and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "containers/podman(\\.git)?\\b" \\
  && ok "origin remote is containers/podman" \\
  || miss "origin remote is not containers/podman (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/podman/client.go" \\
  && ok "cmd/podman/client.go" \\
  || miss "missing critical file: cmd/podman/client.go"
test -f "cmd/podman/common/create.go" \\
  && ok "cmd/podman/common/create.go" \\
  || miss "missing critical file: cmd/podman/common/create.go"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".cirrus.yml" \\
  && ok ".cirrus.yml" \\
  || miss "missing critical file: .cirrus.yml"
test -f "cmd/podman/common/completion.go" \\
  && ok "cmd/podman/common/completion.go" \\
  || miss "missing critical file: cmd/podman/common/completion.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/containers/podman"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Podman is an OCI-compliant container runtime and management tool that provides a Docker-compatible CLI for managing containers, pods, images, and volumes without requiring a daemon process. It's primarily written in Go and runs on Linux natively, with macOS and Windows support via Podman Machine virtual machines. Unlike Docker, Podman emphasizes daemonless operation and rootless container execution. Monorepo structure: libpod/ contains the core container lifecycle library providing APIs, cmd/podman/ implements the CLI interface wrapping libpod, pkg/ houses shared utilities, and test/ contains integration tests. Documentation lives in docs/ with ReadTheDocs configuration (.readthedocs.yaml), build orchestration in .cirrus.yml, and Go module dependencies managed via go.mod/go.sum.

Systems engineers, DevOps practitioners, and container platform maintainers who need to run and manage OCI containers in production or development environments, particularly those working on Kubernetes nodes (where Podman is CRI-compatible) or in constrained/rootless environments where Docker's daemon model is problematic.

Podman is highly mature and production-ready: it releases major/minor versions 4 times yearly (February, May, August, November) with PGP-signed releases, has OpenSSF Best Practices certification, extensive CI/CD via Cirrus CI, and an active maintainer team. The 8.8M lines of Go code, comprehensive test infrastructure, and 4-times-per-year release cadence indicate a stable, well-maintained project used in enterprise Kubernetes distributions.

Low risk for core functionality, but notable considerations: the codebase is large (8.8M Go LOC) with complex OCI/libpod semantics that can have subtle behavioral differences from Docker; breaking changes occur at major version boundaries (currently v6); dependency risk is mitigated by the containers/ org ecosystem (libpod, common, etc.) which Podman tightly controls; single points of failure exist around rootless mode and systemd integration on certain distros.

Active development includes CI/CD improvements (check_cirrus_cron GitHub actions for flaky test detection), release automation (.github/workflows/release.yml and release-artifacts.yml), macOS packaging via GitHub Actions (mac-pkg.yml), and regular security audits (zizmor.yml). The project uses Cirrus CI for primary testing with GitHub Actions for release and maintenance automation.

Clone and build: git clone https://github.com/containers/podman && cd podman && make (requires Go 1.21+). For development: make install installs the binary, make test runs unit tests, make integration runs integration tests. Run podman --version to verify the installation.

Daily commands: Development: make podman builds the binary to bin/. Run ./bin/podman --help for CLI testing, or make test for unit tests. For full integration: make install && podman run quay.io/podman/hello (requires OCI runtime like crun/runc). For rootless testing: podman --root ~/.local/share/containers run --rm alpine echo hello.

• cmd/podman/client.go — Core client initialization and connection logic; every CLI command depends on this entry point.
• cmd/podman/common/create.go — Shared container creation flags and logic used across multiple commands; fundamental to understanding container lifecycle.
• Makefile — Defines build targets, Go module dependencies, and CI integration; required for understanding how to build and test locally.
• .cirrus.yml — Cirrus CI configuration for the entire test and release pipeline; critical for understanding automated quality gates.
• cmd/podman/common/completion.go — Shell completion and CLI introspection; shared across all subcommands and essential for UX.
• cmd/podman/compose.go — Compose workflow orchestration entry point; demonstrates how Podman integrates with Docker Compose semantics.

Add a New Podman Subcommand

1. Create a new .go file in cmd/podman/ for your subcommand (e.g., cmd/podman/newfeature.go) (cmd/podman)
2. Define your command struct and implement rootCmd integration, following the pattern in cmd/podman/auto-update.go or cmd/podman/compose.go (cmd/podman/auto-update.go)
3. Add required flag definitions in cmd/podman/common/create.go or create a new flags file following the pattern of cmd/podman/common/netflags.go (cmd/podman/common/netflags.go)
4. Register completion providers in cmd/podman/common/completion.go for shell integration (cmd/podman/common/completion.go)
5. Write integration tests and update cmd/podman/common/create_test.go as a reference (cmd/podman/common/create_test.go)

Add a Platform-Specific Feature

1. Create platform detection and fallback logic in cmd/podman/client_supported.go for supported platforms or cmd/podman/client_unsupported.go for fallbacks (cmd/podman/client_supported.go)
2. For macOS, implement the feature in cmd/podman-mac-helper/service.go and ensure it's registered in the service lifecycle (cmd/podman-mac-helper/service.go)
3. For Windows/WSL, add logic to cmd/podman/compose_machine_windows.go following the pattern in compose_machine.go (cmd/podman/compose_machine_windows.go)
4. Update Makefile with platform-specific build targets if needed and add CI testing in .cirrus.yml (Makefile)

Add a New Artifact Subcommand

1. Create a new .go file in cmd/podman/artifact/ (e.g., cmd/podman/artifact/newop.go) following patterns in cmd/podman/artifact/pull.go (cmd/podman/artifact/pull.go)
2. Register the command in cmd/podman/artifact/artifact.go alongside existing subcommands (cmd/podman/artifact/artifact.go)
3. Add any artifact-specific flags to cmd/podman/common/create.go or define them inline (cmd/podman/common/create.go)
4. Test the command through integration tests and add completion support via cmd/podman/common/completion.go (cmd/podman/common/completion.go)

• Go — Fast, statically compiled binaries with low memory footprint; ideal for container orchestration tools and cross-platform support (Linux, macOS, Windows).
• libpod (embedded) — Core container and pod management library; decouples CLI from runtime logic, allowing both command-line and API-based access.
• OCI Runtime (runc/crun) + OCI Image Spec — Standards-based container execution and image format; ensures compatibility with other container tools and ecosystem.
• Cobra (CLI framework) — Popular Go CLI framework with built-in shell completion and help generation; enables consistent command structure across Podman subcommands.
• Cirrus CI — Linux, macOS, and Windows native testing; no third-party agent required; integrates tightly with container-based workflows.

• Monolithic CLI binary vs. separate helper binaries

  • Why: Podman provides a single podman binary for ease of distribution, but supplements it with platform-specific helpers (podman-mac-helper, podman-wslkerninst) for OS integration.
  • Consequence: Single entry point reduces user confusion, but platform-specific binaries add installation complexity on macOS and Windows.

• Remote execution via Podman Machine (podman compose_machine.go) instead of in-kernel container runtime

  • Why: On macOS and Windows, native kernel container support is unavailable; using a VM-based machine is the most compatible workaround.
  • Consequence: Extra overhead (~1–2s startup for VM communication), but enables full Docker Compose compatibility and transparent container access.

• Shared flag definitions in cmd/podman/common/ vs. per-command flags

  • Why: Prevents flag duplication and ensures consistent behavior across subcommands; reduces maintenance burden.
  • Consequence: Common code may need frequent updates for new flags, but guarantees consistency.

• Artifact management as a separate subcommand group (cmd/podman/artifact/)

  • Why: Isolates artifact operations (push, pull, extract) from core container/pod/image lifecycle; cleaner separation of concerns.
  • Consequence: Users must learn podman artifact <op> syntax, but the modularity eases future extension (e.g., signing, multi-registry support).

• Does not provide a container orchestration scheduler (not a Kubernetes replacement); Podman manages individual machines only.
• Does not handle distributed image registries natively; delegates to existing registry integrations (via containers/image library).
• Not a real-time monitoring or metrics aggregation system; focuses on

Critical gotchas: (1) Rootless mode requires XDG_RUNTIME_DIR and systemd user session; test failures on CI often relate to ulimit/namespace limits. (2) Different OCI runtimes (crun vs runc) have subtly different behavior; tests may pass locally with crun but fail in CI with runc. (3) Podman socket is usually at /run/podman/podman.sock or /run/user/1000/podman/podman.sock; wrong socket path breaks remote clients. (4) Network namespace sharing between containers is complex; pod networking via Netavark has version dependencies. (5) Buildah is a separate binary (not in this repo) required for podman build if not using native build support. (6) SELinux relabeling (:z/:Z flags) is distro-specific and fails silently on non-SELinux systems.

• OCI (Open Container Initiative) Spec Compliance — Podman is OCI-compliant, meaning it generates and executes OCI Runtime specs and OCI Image specs; understanding OCI contracts is essential for debugging container creation, image compatibility, and runtime behavior differences.
• Daemonless Architecture & Socket Activation — Unlike Docker, Podman runs containers without a persistent daemon, using systemd socket activation for the REST API; this design choice affects how remote Podman works, how state is persisted, and why podman processes are short-lived.
• Rootless Container Execution — Podman's signature feature is running containers as unprivileged users via user namespaces and subuid/subgid mapping; this requires understanding namespace isolation, UID mapping, and XDG_RUNTIME_DIR for security-conscious deployments.
• Pod (libpod Pod Abstraction) — Podman's 'pod' is a group of containers sharing network namespace (like Kubernetes pods); understanding pod plumbing (network namespace attachment, pause containers) is critical for Podman's unique pod features.
• CRIU Checkpoint/Restore — Podman integrates CRIU (Checkpoint/Restore In Userspace) for container live migration and forensics via podman checkpoint and podman restore; understanding container memory snapshots is essential for advanced use cases.
• OCI Runtime Abstraction (crun, runc, kata) — Podman abstracts the OCI runtime behind a common interface; different runtimes (crun for speed, runc for stability, kata for VMs) have different semantics and failure modes that surface during testing.
• systemd Integration & User Sessions — Podman tightly integrates with systemd for rootless container management, lingering sessions, and socket activation; systemd version mismatches or misconfigured user sessions are frequent failure sources.

• containers/libpod — Primary library for container lifecycle management—Podman's runtime core is libpod; note: libpod code IS in this repo under libpod/ but this is the historical canonical location.
• containers/common — Shared utilities, image config handling, and common container specs used by Podman, Buildah, and Skopeo; Podman depends on containers/common for image/registry logic.
• containers/buildah — OCI image builder; Podman's native build uses Buildah as a library (or as a separate binary), making it the de facto standard for podman build layering.
• containers/skopeo — Image copying, inspection, and registry interaction tool; Podman uses Skopeo patterns for remote image operations and image signing/verification.
• containers/netavark — Podman's container networking backend replacing CNI; provides multi-network support, DNS, and network namespace management for Podman containers.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive testing for podman-mac-helper service lifecycle

The cmd/podman-mac-helper directory contains critical service management code (install.go, uninstall.go, service.go) that likely lacks unit tests. Given Podman's macOS support is increasingly important and this helper manages the Podman service on Mac, adding tests for install/uninstall flows, service state transitions, and error handling would catch regressions early and improve reliability for Mac users.

• [ ] Review cmd/podman-mac-helper/*.go files to identify missing test coverage
• [ ] Create cmd/podman-mac-helper/*_test.go files covering install, uninstall, and service lifecycle
• [ ] Add mock helpers for system service operations (launchd interactions on macOS)
• [ ] Ensure tests cover both success and failure scenarios (permissions, already installed, etc.)
• [ ] Reference existing test patterns in the repo and update Makefile test targets if needed

Implement GitHub Actions workflow for podman-testing tool validation

The cmd/podman-testing directory contains a testing utility tool with commands (create.go, remove.go, layer.go, call.go) but there's no dedicated CI workflow in .github/workflows/ to validate this tool's functionality. Adding a workflow would ensure the testing tool itself doesn't regress and works correctly across platforms, supporting the broader test infrastructure.

• [ ] Create .github/workflows/podman-testing-ci.yml workflow file
• [ ] Add build step to compile cmd/podman-testing with multiple Go versions
• [ ] Add validation tests for podman-testing commands (create, remove, layer, call)
• [ ] Configure workflow to run on pushes to cmd/podman-testing/ and pull requests
• [ ] Include platform matrix (Linux) and add appropriate caching for Go modules

Add missing documentation for podman-mac-helper and podman-testing utilities

While build_osx.md and build_windows.md exist, there's no dedicated documentation explaining the cmd/podman-mac-helper helper service or the cmd/podman-testing tool. New contributors and users need clear guides on what these tools do, how to use them, and how they integrate into the Podman workflow. This would fill a documentation gap evident in the file structure.

• [ ] Create docs/mac-helper.md covering podman-mac-helper installation, service management, and troubleshooting
• [ ] Create docs/testing-tool.md explaining podman-testing commands, use cases, and integration with CI/development
• [ ] Reference these docs from the main README.md or a new docs/INDEX.md
• [ ] Include code examples and link to relevant source files (cmd/podman-mac-helper/.go, cmd/podman-testing/.go)
• [ ] Update CONTRIBUTING.md to mention these tools in the development setup section

• Add integration test coverage for podman inspect --format with custom Go template filters in test/integration/inspect/ (currently has gaps for object-path filtering similar to Docker)
• Improve CLI help text consistency across cmd/podman/ subcommands—some flags lack examples and descriptions (e.g., podman run --annotation, podman pod create --share). Add structured examples to pkg/bindings/ documentation.
• Extend libpod/define/errors.go with more specific error types and sentinel values to replace generic wrapping—helps library users distinguish between 'container not found' vs 'network unavailable' vs 'OCI runtime failed'.

The Podman project demonstrates a strong security posture with OpenSSF Best Practices compliance and comprehensive governance documentation. No critical vulnerabilities were identified in the static file structure analysis. The main security improvements would involve: (1) enhancing the SECURITY.md with detailed local procedures rather than external references, (2) implementing strict dependency version pinning in the readthedocs requirements file, and (3) ensuring the LLM policy is comprehensive and well-documented. The project's focus on container security and adherence to industry standards (OCI compliance) is commendable. Regular dependency auditing and security scanning in CI/CD pipelines (evidenced by .cirrus.yml and GitHub workflows) further strengthen the security posture.

• Medium · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file only references an external security policy without providing comprehensive local vulnerability disclosure procedures, response timelines, or contact information directly in the repository. Fix: Expand SECURITY.md to include detailed vulnerability reporting procedures, supported versions, security update timeline expectations, and a clear contact mechanism for security researchers.
• Low · Minimal Dependency Specification in Requirements — requirements file (readthedocs pip installs). The requirements file for readthedocs only specifies 'myst_parser' without version pinning. This could lead to unexpected behavior or security issues if a compromised version is released. Fix: Pin all dependencies to specific versions (e.g., 'myst_parser==0.18.1') and regularly audit for known vulnerabilities. Use tools like pip-audit or Safety to check for CVEs.
• Low · LLM Policy Documentation Present — LLM_POLICY.md. The presence of LLM_POLICY.md suggests awareness of AI/ML security concerns, but the actual policy content is not visible in the provided file structure. This may indicate incomplete security governance for AI-assisted contributions. Fix: Ensure the LLM policy clearly defines acceptable use of LLM-generated code, security review requirements, and liability disclaimers for AI-assisted contributions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.