podman-5-8-2 - SKILL.md Agent Skill

name: podman-5-8-2 description: Daemonless container engine with Docker-compatible CLI for managing containers, pods, images, volumes, and networks. Supports rootless operation, Kubernetes integration, systemd management, and remote access. Use when building, running, or managing containers without a daemon, implementing rootless workflows, orchestrating pods, or migrating from Docker.

Podman 5.8.2

Overview

Podman (the POD MANager) is a daemonless, open source, Linux native tool for managing OCI containers and container images. It provides a command line interface familiar to anyone who has used Docker — most users can simply alias docker=podman without issues. Podman manages the entire container ecosystem including pods, containers, images, and volumes using the libpod library.

Key differentiators from Docker:

No daemon — improved security and lower resource utilization at idle
Rootless by design — containers run as normal users via user namespaces, no setuid binary required
Pods support — groups of containers sharing resources, similar to Kubernetes pods
Systemd integration — declarative container management via Quadlet unit files
Remote client — manage containers on remote Linux hosts over SSH from Mac/Windows/Linux
Kubernetes integration — kube play and kube generate for bidirectional YAML conversion

Podman uses best-of-breed OCI libraries: crun or runc for runtime, Netavark for networking, pasta for rootless networking, Buildah for image builds, and containers/storage (SQLite backend, BoltDB deprecated in 6.0) for storage.

When to Use

Building, running, or managing OCI containers without a background daemon
Implementing rootless container workflows where users run containers without root privileges
Deploying container workloads on Mac or Windows via podman machine virtual machines
Managing containers declaratively with systemd via Quadlet unit files
Converting between Podman containers and Kubernetes YAML with kube play/kube generate
Automating container lifecycle management in CI/CD pipelines
Migrating from Docker to a daemonless alternative (alias docker=podman)
Running containers remotely over SSH from any platform
Managing OCI artifacts alongside container images
Configuring complex container networking with Netavark and pasta

Version Notes (5.8.2)

This patch release includes:

Security: Fixes CVE-2026-33414 — podman machine init --image on Windows with Hyper-V backend could execute Powershell-escaped commands from user-specified image paths on the host
Bugfixes: unless-stopped restart policy now works after reboot with podman-restart.service; Quadlet Entrypoint="" correctly clears entrypoint; Quadlet HealthCmd with double-quotes parses correctly; FreeBSD panic on container inspect with host network mode resolved
API: Libpod System Check endpoint no longer performs operations with bad data after 400 errors; remote attach API race condition fixed; Secret Create API with shell driver now produces functional secrets
Dependencies: Buildah v1.43.1, containers/common v0.67.1, containers/image v5.39.2

Core Concepts

Daemonless architecture: Unlike Docker, Podman has no persistent daemon. Each podman command forks a new process. Containers are managed through fork-exec, making the system more resilient — killing the podman process does not affect running containers. Conmon monitors container processes and handles cleanup.

Rootless containers: Podman runs containers as a normal user without root privileges. User namespaces map the container's root UID to the host user's UID. The administrator configures /etc/subuid and /etc/subgid to allocate UID/GID ranges per user. Rootless containers never have more privileges than the launching user.

Pods: A pod is a group of containers that share the same network namespace, IPC namespace, and optionally other resources. Pods provide a Kubernetes-like grouping without requiring a full orchestrator. The infra container manages shared resources.

Quadlet: Declarative container management using systemd unit files. Quadlet translates .container, .pod, .volume, .network, .image, and .build unit files into Podman commands, enabling containers to be managed as systemd services with automatic restart, dependencies, and lifecycle management.

Remote client: Podman on Mac and Windows connects to a Linux backend (managed VM or external server) over SSH. The podman-remote binary or podman --remote communicates with the Podman REST API exposed via podman.socket.

Installation / Setup

Podman is available on most Linux distributions via package managers (apt, dnf, yum, zypper). On Mac and Windows, install from podman.io — it includes a managed VM backend.

For rootless operation, the administrator must:

Install pasta (rootless networking tool, package name passt)
Configure subordinate UIDs/GIDs in /etc/subuid and /etc/subgid:

usermod --add-subuids 100000-165535 --add-subgids 100000-165535 johndoe

Enable linger for persistent rootless socket (optional):

sudo loginctl enable-linger $USER

Configuration files are read in this order (later overrides earlier):

/usr/share/containers/containers.conf → /etc/containers/containers.conf → $HOME/.config/containers/containers.conf
/etc/containers/storage.conf → $HOME/.config/containers/storage.conf
/etc/containers/registries.conf → /etc/containers/registries.d/* → $HOME/.config/containers/registries.conf

Usage Examples

Run a simple container:

podman run --rm -it alpine sh

Run with port mapping and volume mount:

podman run -d --name web -p 8080:80 -v ./data:/data nginx

Build an image from a Containerfile:

podman build -t myapp:latest .

Manage pods:

podman pod create --name mypod --port 8080:80
podman run -d --pod mypod nginx
podman run -d --pod mypod redis

Rootless container with keep-id namespace:

podman run --rm --userns=keep-id -v $PWD:/work alpine ls -la /work

Kubernetes play:

podman kube play app.yaml
podman kube down app.yaml

Advanced Topics

Rootless Containers: Detailed setup, user namespace configuration, volume semantics, and known limitations → Rootless Containers

Pods and Pod Management: Creating pods, shared namespaces, lifecycle management, pod stats → Pod Management

Networking with Netavark and Pasta: Bridge networks, pasta rootless networking, DNS, subnet pools, network options → Networking

Quadlet and Systemd Integration: Declarative container management via systemd unit files, .container, .pod, .volume units, service generation → Quadlet and Systemd

Remote Client and podman machine: Managing containers over SSH, Mac/Windows VM backends, connection configuration, libkrun/applehv providers → Remote Client and Machine

Kubernetes Integration: kube play, kube generate, kube down, bidirectional YAML conversion, CDI device support → Kubernetes Integration

Container Image Management: Building, pulling, pushing, tagging, importing, OCI artifacts, trust policies → Image Management

Volumes and Storage: Named volumes, bind mounts, volume plugins, storage drivers (overlay, VFS), SQLite backend → Volumes and Storage

REST API and Docker Compatibility: Libpod API, Docker-compatible API endpoints, healthchecks, service socket → REST API

Command Reference: Summary of all major Podman command groups — container, image, pod, network, volume, system, machine, quadlet, kube, artifact → Command Reference