How containers/podman works
1. Repository purpose and top-level shape
This is the source tree for Podman itself, not a single service. It builds several binaries, with cmd/podman as the main CLI, plus supporting tools like quadlet, rootlessport, podman-machine helpers, and Windows/Mac-specific utilities. The core product is a container/image/pod manager, but the repo also contains the API server, client bindings, VM management, packaging, docs, and extensive integration tests.
2. Primary user entrypoints
The main user-facing flow starts in cmd/podman/main.go and fans out into command subpackages such as containers, images, pods, networks, volumes, system, manifest, secret, kube, machine, and quadlet. These commands are thin orchestration layers: they parse CLI flags, validate input, and call into the domain layer rather than implementing container logic themselves.
3. Domain layer as the command/service boundary
pkg/domain is the central abstraction boundary. It defines operation-oriented entities and options, then splits implementation into pkg/domain/infra/abi and pkg/domain/infra/tunnel. This lets the same high-level Podman semantics run either against a local libpod/OCI environment or against a remote Podman service over HTTP.
4. Local engine and libpod core
libpod is the local container engine and state manager. It owns lifecycle and state for containers, pods, images, volumes, events, health checks, storage integration, locking, and OCI runtime coordination. The higher layers call into libpod through the ABI path, which is where most of the real container/pod behavior lives.
5. Remote/client architecture
Remote usage is handled by the tunnel path: the CLI uses pkg/domain/infra/tunnel and pkg/bindings to talk to a Podman service over HTTP. pkg/api/server exposes the service endpoints, while pkg/api/handlers/libpod and pkg/api/handlers/compat implement two API surfaces: Podman-native and Docker-compatible. This is the main local-vs-remote architectural boundary in the repo.
6. HTTP API and compatibility layer
The API subsystem is structured as server registration plus handler groups per resource type: containers, images, pods, networks, volumes, secrets, system, events, kube, manifests, artifacts, and quadlets. pkg/api/handlers/compat mirrors Docker-style endpoints, while pkg/api/handlers/libpod exposes Podman-specific behavior. Generated or structured types live in pkg/api/types and pkg/api/handlers/types, and pkg/bindings is the client-side mirror of those APIs.
7. Container and image lifecycle flow
The main data flow is: CLI request → domain layer → libpod/ABI or tunnel → storage/runtime/network subsystems. Image actions use containers/image concepts through Podman’s wrappers and trust policy in pkg/trust; build flows integrate Buildah via its Go API, as the README notes. Container creation uses pkg/specgen and pkg/specgenutil to normalize runtime config before runtime launch.
8. Runtime, OCI, and process supervision
OCI execution is coordinated by libpod/oci* and related runtime helpers. Podman uses an OCI runtime such as crun or runc, with conmon as the monitor process between Podman and the OCI runtime. Process handling, exit codes, signal propagation, attach/exec, and terminal behavior are isolated into dedicated packages like pkg/channel, pkg/terminal, pkg/signal, pkg/pidhandle, and the oci_conmon_* files.
9. Storage, volumes, and filesystem state
Container/image/volume persistence is separated from runtime state. libpod/storage.go, libpod/volume.go, and related state files manage persisted objects, while containers/storage is the underlying external storage engine mentioned in the README. There is also explicit support for copy/mount/export/import operations and for mount/volume inspection paths in both the CLI and API layers.
10. Networking and rootless execution
Networking is split across Linux, FreeBSD, machine, and rootless variants. The repo references Netavark/Aardvark and pasta for rootless networking, with helper code in libpod/networking_*, pkg/machine/ports, pkg/machine/gvproxy*, and cmd/rootlessport. Rootless support is a first-class boundary: pkg/rootless, user namespaces, subuid/subgid mapping, and platform-specific fallbacks are used throughout the CLI and engine.
11. Podman Machine and cross-platform virtualization
Non-Linux Podman depends on pkg/machine and the cmd/podman-machine family to manage a lightweight VM that hosts the Linux engine. That subsystem contains platform-specific implementations for macOS, Hyper-V/WSL on Windows, and QEMU/VFKit/libkrun-style providers, plus image/boot/config/SSH/connection management. cmd/podman-mac-helper and cmd/podman-wslkerninst are platform helpers that support this VM-based architecture.
12. System integration and developer-facing orchestration
pkg/systemd and pkg/systemd/quadlet generate or parse systemd units and Quadlet definitions, bridging container definitions into host service management. pkg/autoupdate, pkg/farm, pkg/checkpoint, pkg/criu, pkg/seccomp, and pkg/selinux are supporting subsystems that extend container lifecycle, security, and operational automation. These are not core execution paths, but they materially affect how containers are launched and managed on real systems.
13. Testing and release/packaging boundaries
The repository has multiple test strata: Go unit tests, BATS/system tests under test/system, API tests under test/apiv2, and large end-to-end suites under test/e2e and pkg/machine/e2e. Packaging and distribution are also first-class, with RPM, Windows installer, macOS package, docs generation, and CI workflows under .github, rpm, contrib, and docs. For an architecture diagram, these should be shown as external validation and delivery layers around the core engine/API/client stack, not as part of runtime execution.
Main entry points: create.go Command sets · runtime.go Runtime core · containers.go ABI engine · server.go API server
Components 23
CLI
User-facing command entrypoints and option parsing
- podman CLI · Main CLI binary and command router
cmd/podman/main.go - Command sets · Container, image, pod, network, volume, system, kube, manifest, secret, machine, quadlet, and related commands
cmd/podman/containers/create.go - Root wiring · Global command setup, shared flags, validation, and runtime selection
cmd/podman/root.go
Domain
Operation boundary shared by local and remote execution
- Domain model · Operation entities, options, reports, and shared CLI/API abstractions
pkg/domain/entities/containers.go - ABI engine · Local execution path from domain operations into libpod
pkg/domain/infra/abi/containers.go - Tunnel client · Remote execution path from domain operations over HTTP bindings
pkg/domain/infra/tunnel/containers.go
Engine
Local container engine and runtime state
- Runtime core · Stateful container, pod, image, and volume orchestration
libpod/runtime.go - OCI launch · OCI runtime coordination, conmon supervision, attach/exec, and signal handling
libpod/oci.go - Storage layer · Persistent container and volume storage integration
libpod/storage.go - Networking · Container networking, rootless networking, and platform-specific network helpers
libpod/networking_linux.go - Specgen · Container and pod spec generation, validation, and runtime config normalization
pkg/specgen/specgen.go - Image trust · Signature and policy enforcement for image operations
pkg/trust/trust.go
API
HTTP server, handlers, and client bindings
- API server · HTTP server registration, routing, and middleware
pkg/api/server/server.go - Podman API · Podman-native resource handlers for containers, images, pods, networks, volumes, secrets, system, kube, manifests, quadlets, and artifacts
pkg/api/handlers/libpod/containers.go - Compat API · Docker-compatible handler surface layered over Podman semantics
pkg/api/handlers/compat/containers.go - Bindings · Go client bindings that mirror the HTTP API
pkg/bindings/containers/containers.go
Machine
VM-based engine support for non-Linux hosts
- Machine · VM-backed Linux engine management for macOS and Windows
pkg/machine/machine_common.go - rootlessport · Helper binary for rootless port forwarding and WSL support
cmd/rootlessport/main.go
System
System integration, security, and packaging support
- Quadlet · Generate and parse systemd units and Quadlet definitions
pkg/systemd/quadlet/quadlet.go - Systemd gen · Container and pod unit generation and activation helpers
pkg/systemd/generate/containers.go
Validation
Integration and end-to-end test layers
- E2E tests · End-to-end CLI and remote behavior coverage
test/e2e/libpod_suite_test.go - API tests · HTTP API compatibility and resource coverage
test/apiv2/01-basic.at - System tests · System-level CLI, networking, storage, and runtime integration tests
test/system/001-basic.bats
Connections 24
- podman CLI → Root wiring: boots · Initializes global CLI state and runtime selection
- Root wiring → Command sets: dispatches · Routes into major command groups
- Command sets → Domain model: builds ops · Translates flags and args into domain operations
- Domain model → ABI engine: local path · Executes against the local engine via ABI
- Domain model → Tunnel client: remote path · Executes over the tunnel/client path
- ABI engine → Runtime core: calls · Local domain operations drive libpod runtime state
- ABI engine → Specgen: normalizes · Builds runtime configuration before create/run
- ABI engine → Image trust: verifies · Applies image trust and policy checks
- Runtime core → Storage layer: persists · Stores and reloads container, pod, and volume state
- Runtime core → OCI launch: launches · Starts and supervises OCI workloads
- Runtime core → Networking: connects · Configures container and pod networking
- Tunnel client → Bindings: uses · Sends HTTP requests through generated client bindings
- Bindings → API server: calls · Targets the server-side HTTP API
- API server → Podman API: registers · Installs Podman-specific resource handlers
- API server → Compat API: registers · Installs Docker-compatible handlers
- Podman API → Runtime core: serves · Maps API requests to engine operations
- Compat API → Runtime core: adapts · Reuses engine behavior behind compatibility endpoints
- Machine → rootlessport: depends on · Uses helper binaries for networking and platform integration
- Command sets → Machine: manages · Machine subcommands control VM-backed environments
- Command sets → Systemd gen: generates · Systemd-related command flows produce units
- Command sets → Quadlet: parses · Quadlet commands bridge container specs into systemd
- E2E tests → Command sets: exercises · Validates CLI and command behavior end to end
- API tests → API server: exercises · Validates HTTP API surfaces and resource semantics
- System tests → Command sets: exercises · Covers CLI flows, runtime behavior, and host integration