podman/AGENTS.md

AI Agent Guide for Podman Development

This document is specifically designed for AI coding assistants (like Claude, ChatGPT, Copilot) to provide context and guidance when helping developers with Podman-related tasks. It contains essential information about codebase structure, development patterns, testing frameworks, and common pitfalls that AI agents should be aware of when assisting with Podman development, debugging, and contributions.

Project Overview

Podman is a daemonless container engine with Docker-compatible CLI, rootless support, native pod management, and systemd integration via Quadlet.

Quick Start

# Build and test
make binaries           # Build all binaries
make validatepr         # Format, lint, and validate (required for PRs)
make localintegration   # Run integration tests
make localsystem        # Run system tests

# Development tools
make install.tools      # Install linters and dev tools

Codebase Structure

podman/
├── cmd/podman/               # CLI commands (Cobra framework)
├── cmd/quadlet/              # Quadlet systemd unit generator
├── libpod/                   # Core container/pod management (Linux only)
├── pkg/
│   ├── api/                  # REST API server
│   ├── bindings/             # HTTP client (stable API)
│   ├── domain/               # Business logic layer
│   │   ├── entities/         # Interfaces and data structures
│   │   ├── infra/abi/        # Local implementation
│   │   └── infra/tunnel/     # Remote implementation
│   └── specgen/              # Container/pod specifications
├── test/e2e/                 # Integration tests (Ginkgo)
├── test/system/              # System tests (BATS)
├── docs/source/markdown/     # Man pages
└── vendor/                   # Vendored dependencies (DO NOT EDIT)

Development Patterns

CLI Command Pattern

// cmd/podman/command.go
var commandCmd = &cobra.Command{
    Use:   "command [options] args",
    RunE:  commandRun,
}

func commandRun(cmd *cobra.Command, args []string) error {
    return registry.ContainerEngine().Command(registry.GetContext(), options)
}

Domain Layer Pattern

// pkg/domain/infra/abi/command.go (local)
func (ic *ContainerEngine) Command(ctx context.Context, options entities.CommandOptions) error {
    return ic.Libpod.Command(options)  // Direct libpod call
}

// pkg/domain/infra/tunnel/command.go (remote)
func (ic *ContainerEngine) Command(ctx context.Context, options entities.CommandOptions) error {
    return bindings.Command(ic.ClientCtx, options)  // HTTP API call
}

Testing

Integration Tests (Ginkgo)

Integration Tests (test/e2e/): Test Podman CLI commands end-to-end, using actual binaries and real containers. Use for testing user-facing functionality and CLI behavior.

It("should work correctly", func() {
    session := podmanTest.Podman([]string{"command", "args"})
    session.WaitWithDefaultTimeout()
    Expect(session).Should(Exit(0))
})

System Tests (BATS)

System Tests (test/system/): Test Podman in realistic environments with shell scripts. Use for testing complex scenarios, multi-command workflows, and system integration.

@test "podman command functionality" {
    run_podman command --option value
    is "$output" "expected output" "description"
}

Code Standards

Official Documentation: CONTRIBUTING.md

• Formatter: gofumpt (via golangci-lint, configured in .golangci.yml)
• Validation: All PRs must pass make validatepr
• Commits: Must be signed (git commit -s) and follow DCO
• Reviews: Two approvals required for merge

Key Libraries

• aardvark-dns: Container DNS server
• Cobra: CLI framework used for cmd/podman commands
• containers/buildah: Image building
• containers/container-libs: Shared utilities
• crun: Fast, low-memory container runtime
• Go: Programming language
• gorilla/mux: HTTP router and URL matcher for REST API
• gorilla/schema: Form data to struct conversion
• netavark: Network management
• runc: OCI-compliant container runtime

Common Pitfalls for AI Agents

1. Never edit vendor/ - Use go get then make vendor
2. Platform awareness - Consider Linux/Windows/macOS differences
3. Rootless vs root - Many behaviors differ between modes
4. Remote vs local - Different code paths (abi vs tunnel)
5. Test cleanup - Always clean up test artifacts

Essential Commands

# Analysis
go list -tags "$BUILDTAGS" -f '{{.Deps}}' ./cmd/podman  # Dependencies
grep -r "pattern" --include="*.go" .                    # Find patterns

# Testing
make localintegration FOCUS_FILE=your_test.go           # Single test file
make localintegration FOCUS="test description"          # Single test
PODMAN_TEST_SKIP_CLEANUP=1 make localintegration        # Debug mode

# Validation
make validatepr                                         # Full validation
make lint                                               # Linting only

Documentation

• CONTRIBUTING.md: Development guidelines
• DISTRO_PACKAGE.md: Packaging guidelines for distributors
• docs/CODE_STRUCTURE.md: Detailed codebase structure
• docs/tutorials/: Step-by-step guides and tutorials
• GOVERNANCE.md: Project organization and contributor roles
• LICENSE: Apache 2.0 license terms
• README.md: Project overview
• RELEASE_PROCESS.md: Release workflow (maintainers only)
• rootless.md: Rootless limitations and troubleshooting
• test/README.md: Testing framework details

For comprehensive information, refer to the official documentation and recent commits in the Podman repository.