podman/AGENTS.md

AI Agent Guide for Podman Development

Quick reference guide for AI agents assisting with Podman development.

Project Overview

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

Key Technologies: Cobra, containers/image, containers/storage, crun, Go, Netavark, runc

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)
├── 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)

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

System Tests (BATS)

@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

• containers/buildah: Image building
• containers/common: Shared utilities
• containers/image: Image management
• containers/storage: Container and image storage
• gorilla/mux: HTTP router and URL matcher for REST API
• gorilla/schema: Form data to struct conversion
• netavark: Network management

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.