[Phase 3] Verify Podman compatibility and absorb runtime differences

[Saber5656]

Background

NFR-5 requires support for both Docker and Podman. After the runtime abstraction exists, Cage still needs compatibility validation for CLI flags, networking, security options, and rootless behavior.

Scope

• Verify Podman availability detection.
• Verify compatibility for create, start, exec, cp, and network operations.
• Check whether hardening flags work under rootless Podman.
• Document Podman-in-Podman or DinD-equivalent behavior.
• Keep Docker and Podman differences inside the runtime abstraction.

Acceptance Criteria

• --podman explicitly selects the Podman runtime.
• Missing Podman produces an understandable error.
• Podman-specific differences are documented.
• Podman unit or integration tests are added without breaking Docker tests.

References

• cage-demo/docs/architecture/tech-selection.md section 2
• cage-demo/src/engine/podman.rs
• cage-demo/docs/PRD.md NFR-5

Technical Audit Addendum (2026-07-06)

Concrete Podman differences to absorb (beyond flag compatibility):

• Rootless uid mapping: the hardening layer passes --user <host-uid>:<host-gid> (SEC-ISSUE-005); under rootless Podman this interacts with user namespaces — support/allow --userns=keep-id and verify workspace file ownership survives podman cp round-trips.
• Resource limits under rootless: --memory/--pids-limit require cgroups v2 delegation and may be unavailable; decide warn-and-continue vs fail-closed, and test both paths.
• Detection: runtime auto-detection must not misidentify a Podman socket exposed as a Docker-compatible API; --podman and CAGE_RUNTIME must win over auto-detection.
• macOS: podman machine adds another VM boundary (volume and tmpfs semantics differ from Docker Desktop); mark it tested/best-effort in the platform matrix ([Phase 3] Define and validate the platform support matrix (macOS/Linux/WSL2, runtimes) #28) rather than assuming parity.
• DinD equivalence: document Podman-in-Podman (quay.io/podman/stable, --userns=keep-id) as the --dind counterpart or explicitly defer it ([Phase 3] Provide a safe DinD sidecar mode #20).