# containers/podman architecture

> Architecture diagram of the GitHub repository containers/podman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/containers/podman
- Repository: https://github.com/containers/podman

## Overview

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: [`cmd/podman/containers/create.go`](https://github.com/containers/podman/blob/main/cmd/podman/containers/create.go) (Command sets), [`libpod/runtime.go`](https://github.com/containers/podman/blob/main/libpod/runtime.go) (Runtime core), [`pkg/domain/infra/abi/containers.go`](https://github.com/containers/podman/blob/main/pkg/domain/infra/abi/containers.go) (ABI engine), [`pkg/api/server/server.go`](https://github.com/containers/podman/blob/main/pkg/api/server/server.go) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cmd_podman_main["podman CLI<br/>entrypoint<br/>[main.go]"]
  node_cmd_podman_commands["Command sets<br/>cli subcommands<br/>[create.go]"]
  node_cmd_podman_root["Root wiring<br/>cli bootstrap<br/>[root.go]"]
end

subgraph group_domain["Domain"]
  node_pkg_domain_entities["Domain model<br/>operations schema<br/>[containers.go]"]
  node_pkg_domain_abi["ABI engine<br/>local domain impl<br/>[containers.go]"]
  node_pkg_domain_tunnel["Tunnel client<br/>remote domain impl<br/>[containers.go]"]
end

subgraph group_engine["Engine"]
  node_libpod_runtime[("Runtime core<br/>container engine<br/>[runtime.go]")]
  node_libpod_oci["OCI launch<br/>process runtime<br/>[oci.go]"]
  node_libpod_storage[("Storage layer<br/>persistence<br/>[storage.go]")]
  node_libpod_network["Networking"]
  node_pkg_specgen["Specgen<br/>config normalization<br/>[specgen.go]"]
  node_pkg_trust["Image trust<br/>policy<br/>[trust.go]"]
end

subgraph group_api["API"]
  node_pkg_api_server["API server<br/>http server<br/>[server.go]"]
  node_pkg_api_libpod["Podman API<br/>handler set<br/>[containers.go]"]
  node_pkg_api_compat["Compat API<br/>docker api<br/>[containers.go]"]
  node_pkg_bindings["Bindings<br/>client SDK<br/>[containers.go]"]
end

subgraph group_machine["Machine"]
  node_pkg_machine[("Machine<br/>vm manager<br/>[machine_common.go]")]
  node_cmd_rootlessport["rootlessport<br/>port forwarder<br/>[main.go]"]
end

subgraph group_system["System"]
  node_pkg_systemd_quadlet["Quadlet<br/>systemd bridge<br/>[quadlet.go]"]
  node_pkg_systemd_generate["Systemd gen<br/>unit generation<br/>[containers.go]"]
end

subgraph group_tests["Validation"]
  node_test_e2e["E2E tests<br/>integration suite"]
  node_test_apiv2["API tests<br/>api suite<br/>[01-basic.at]"]
  node_test_system["System tests<br/>bats suite<br/>[001-basic.bats]"]
end

node_cmd_podman_main -->|"boots"| node_cmd_podman_root
node_cmd_podman_root -->|"dispatches"| node_cmd_podman_commands
node_cmd_podman_commands -->|"builds ops"| node_pkg_domain_entities
node_pkg_domain_entities -->|"local path"| node_pkg_domain_abi
node_pkg_domain_entities -->|"remote path"| node_pkg_domain_tunnel
node_pkg_domain_abi -->|"calls"| node_libpod_runtime
node_pkg_domain_abi -->|"normalizes"| node_pkg_specgen
node_pkg_domain_abi -->|"verifies"| node_pkg_trust
node_libpod_runtime -->|"persists"| node_libpod_storage
node_libpod_runtime -->|"launches"| node_libpod_oci
node_libpod_runtime -->|"connects"| node_libpod_network
node_pkg_domain_tunnel -->|"uses"| node_pkg_bindings
node_pkg_bindings -->|"calls"| node_pkg_api_server
node_pkg_api_server -->|"registers"| node_pkg_api_libpod
node_pkg_api_server -->|"registers"| node_pkg_api_compat
node_pkg_api_libpod -->|"serves"| node_libpod_runtime
node_pkg_api_compat -->|"adapts"| node_libpod_runtime
node_pkg_machine -->|"depends on"| node_cmd_rootlessport
node_cmd_podman_commands -->|"manages"| node_pkg_machine
node_cmd_podman_commands -->|"generates"| node_pkg_systemd_generate
node_cmd_podman_commands -->|"parses"| node_pkg_systemd_quadlet
node_test_e2e -.->|"exercises"| node_cmd_podman_commands
node_test_apiv2 -.->|"exercises"| node_pkg_api_server
node_test_system -.->|"exercises"| node_cmd_podman_commands

click node_cmd_podman_main "https://github.com/containers/podman/blob/main/cmd/podman/main.go"
click node_cmd_podman_commands "https://github.com/containers/podman/blob/main/cmd/podman/containers/create.go"
click node_cmd_podman_root "https://github.com/containers/podman/blob/main/cmd/podman/root.go"
click node_pkg_domain_entities "https://github.com/containers/podman/blob/main/pkg/domain/entities/containers.go"
click node_pkg_domain_abi "https://github.com/containers/podman/blob/main/pkg/domain/infra/abi/containers.go"
click node_pkg_domain_tunnel "https://github.com/containers/podman/blob/main/pkg/domain/infra/tunnel/containers.go"
click node_libpod_runtime "https://github.com/containers/podman/blob/main/libpod/runtime.go"
click node_libpod_oci "https://github.com/containers/podman/blob/main/libpod/oci.go"
click node_libpod_storage "https://github.com/containers/podman/blob/main/libpod/storage.go"
click node_libpod_network "https://github.com/containers/podman/blob/main/libpod/networking_linux.go"
click node_pkg_specgen "https://github.com/containers/podman/blob/main/pkg/specgen/specgen.go"
click node_pkg_trust "https://github.com/containers/podman/blob/main/pkg/trust/trust.go"
click node_pkg_api_server "https://github.com/containers/podman/blob/main/pkg/api/server/server.go"
click node_pkg_api_libpod "https://github.com/containers/podman/blob/main/pkg/api/handlers/libpod/containers.go"
click node_pkg_api_compat "https://github.com/containers/podman/blob/main/pkg/api/handlers/compat/containers.go"
click node_pkg_bindings "https://github.com/containers/podman/blob/main/pkg/bindings/containers/containers.go"
click node_pkg_machine "https://github.com/containers/podman/blob/main/pkg/machine/machine_common.go"
click node_cmd_rootlessport "https://github.com/containers/podman/blob/main/cmd/rootlessport/main.go"
click node_pkg_systemd_quadlet "https://github.com/containers/podman/blob/main/pkg/systemd/quadlet/quadlet.go"
click node_pkg_systemd_generate "https://github.com/containers/podman/blob/main/pkg/systemd/generate/containers.go"
click node_test_e2e "https://github.com/containers/podman/blob/main/test/e2e/libpod_suite_test.go"
click node_test_apiv2 "https://github.com/containers/podman/blob/main/test/apiv2/01-basic.at"
click node_test_system "https://github.com/containers/podman/blob/main/test/system/001-basic.bats"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_podman_main,node_cmd_podman_commands,node_cmd_podman_root,node_test_e2e,node_test_apiv2,node_test_system toneBlue
class node_pkg_domain_entities,node_pkg_domain_abi,node_pkg_domain_tunnel toneAmber
class node_libpod_runtime,node_libpod_oci,node_libpod_storage,node_libpod_network,node_pkg_specgen,node_pkg_trust toneMint
class node_pkg_api_server,node_pkg_api_libpod,node_pkg_api_compat,node_pkg_bindings toneRose
class node_pkg_machine,node_cmd_rootlessport toneIndigo
class node_pkg_systemd_quadlet,node_pkg_systemd_generate toneTeal
```

## Components

### CLI

User-facing command entrypoints and option parsing

- [podman CLI](https://github.com/containers/podman/blob/main/cmd/podman/main.go): entrypoint · Main CLI binary and command router · `cmd/podman/main.go`
- [Command sets](https://github.com/containers/podman/blob/main/cmd/podman/containers/create.go): cli subcommands · Container, image, pod, network, volume, system, kube, manifest, secret, machine, quadlet, and related commands · `cmd/podman/containers/create.go`
- [Root wiring](https://github.com/containers/podman/blob/main/cmd/podman/root.go): cli bootstrap · Global command setup, shared flags, validation, and runtime selection · `cmd/podman/root.go`

### Domain

Operation boundary shared by local and remote execution

- [Domain model](https://github.com/containers/podman/blob/main/pkg/domain/entities/containers.go): operations schema · Operation entities, options, reports, and shared CLI/API abstractions · `pkg/domain/entities/containers.go`
- [ABI engine](https://github.com/containers/podman/blob/main/pkg/domain/infra/abi/containers.go): local domain impl · Local execution path from domain operations into libpod · `pkg/domain/infra/abi/containers.go`
- [Tunnel client](https://github.com/containers/podman/blob/main/pkg/domain/infra/tunnel/containers.go): remote domain impl · Remote execution path from domain operations over HTTP bindings · `pkg/domain/infra/tunnel/containers.go`

### Engine

Local container engine and runtime state

- [Runtime core](https://github.com/containers/podman/blob/main/libpod/runtime.go): container engine · Stateful container, pod, image, and volume orchestration · `libpod/runtime.go`
- [OCI launch](https://github.com/containers/podman/blob/main/libpod/oci.go): process runtime · OCI runtime coordination, conmon supervision, attach/exec, and signal handling · `libpod/oci.go`
- [Storage layer](https://github.com/containers/podman/blob/main/libpod/storage.go): persistence · Persistent container and volume storage integration · `libpod/storage.go`
- [Networking](https://github.com/containers/podman/blob/main/libpod/networking_linux.go): runtime networking · Container networking, rootless networking, and platform-specific network helpers · `libpod/networking_linux.go`
- [Specgen](https://github.com/containers/podman/blob/main/pkg/specgen/specgen.go): config normalization · Container and pod spec generation, validation, and runtime config normalization · `pkg/specgen/specgen.go`
- [Image trust](https://github.com/containers/podman/blob/main/pkg/trust/trust.go): policy · Signature and policy enforcement for image operations · `pkg/trust/trust.go`

### API

HTTP server, handlers, and client bindings

- [API server](https://github.com/containers/podman/blob/main/pkg/api/server/server.go): http server · HTTP server registration, routing, and middleware · `pkg/api/server/server.go`
- [Podman API](https://github.com/containers/podman/blob/main/pkg/api/handlers/libpod/containers.go): handler set · 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](https://github.com/containers/podman/blob/main/pkg/api/handlers/compat/containers.go): docker api · Docker-compatible handler surface layered over Podman semantics · `pkg/api/handlers/compat/containers.go`
- [Bindings](https://github.com/containers/podman/blob/main/pkg/bindings/containers/containers.go): client SDK · Go client bindings that mirror the HTTP API · `pkg/bindings/containers/containers.go`

### Machine

VM-based engine support for non-Linux hosts

- [Machine](https://github.com/containers/podman/blob/main/pkg/machine/machine_common.go): vm manager · VM-backed Linux engine management for macOS and Windows · `pkg/machine/machine_common.go`
- [rootlessport](https://github.com/containers/podman/blob/main/cmd/rootlessport/main.go): port forwarder · Helper binary for rootless port forwarding and WSL support · `cmd/rootlessport/main.go`

### System

System integration, security, and packaging support

- [Quadlet](https://github.com/containers/podman/blob/main/pkg/systemd/quadlet/quadlet.go): systemd bridge · Generate and parse systemd units and Quadlet definitions · `pkg/systemd/quadlet/quadlet.go`
- [Systemd gen](https://github.com/containers/podman/blob/main/pkg/systemd/generate/containers.go): unit generation · Container and pod unit generation and activation helpers · `pkg/systemd/generate/containers.go`

### Validation

Integration and end-to-end test layers

- [E2E tests](https://github.com/containers/podman/blob/main/test/e2e/libpod_suite_test.go): integration suite · End-to-end CLI and remote behavior coverage · `test/e2e/libpod_suite_test.go`
- [API tests](https://github.com/containers/podman/blob/main/test/apiv2/01-basic.at): api suite · HTTP API compatibility and resource coverage · `test/apiv2/01-basic.at`
- [System tests](https://github.com/containers/podman/blob/main/test/system/001-basic.bats): bats suite · System-level CLI, networking, storage, and runtime integration tests · `test/system/001-basic.bats`

## Connections

- 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
