Backend: Podman (Experimental)

Podman backend configuration variables for agents. The Podman backend uses the native Podman Go SDK (github.com/containers/podman) for direct communication with Podman, supporting both rootful and rootless installations.

Socket Configuration

BACKEND_PODMAN_HOST

Name: CROW_BACKEND_PODMAN_HOST
Description: Podman socket address. If not set, auto-detects the socket location (rootful at /run/podman/podman.sock, rootless at $XDG_RUNTIME_DIR/podman/podman.sock).
Default: auto-detect

Network

BACKEND_PODMAN_NETWORK

Name: CROW_BACKEND_PODMAN_NETWORK
Description: Podman network which will be attached to all pipeline steps. Careful: this allows containers of different steps to communicate with each other.
Default: none

BACKEND_PODMAN_ENABLE_IPV6

Name: CROW_BACKEND_PODMAN_ENABLE_IPV6
Description: Whether to enable IPv6 support in Podman containers. Requires the Podman network to be configured with IPv6 support.
Default: false

BACKEND_PODMAN_NETWORK_KEEPALIVE_INTERVAL

Name: CROW_BACKEND_PODMAN_NETWORK_KEEPALIVE_INTERVAL
Description: Interval for an optional helper container that periodically issues DNS lookups on the workflow network. This can mitigate Podman network DNS/HTTPS failures after long idle periods. Example values: 30s, 1m.
Default: disabled (empty)

BACKEND_PODMAN_NETWORK_KEEPALIVE_IMAGE

Name: CROW_BACKEND_PODMAN_NETWORK_KEEPALIVE_IMAGE
Description: Container image used for the optional network keepalive helper. The image must provide /bin/sh and nslookup.
Default: docker.io/library/busybox:1.37.0

BACKEND_PODMAN_NETWORK_KEEPALIVE_HOST

Name: CROW_BACKEND_PODMAN_NETWORK_KEEPALIVE_HOST
Description: Hostname or IP queried by the optional network keepalive helper.
Default: example.com

Volumes

BACKEND_PODMAN_VOLUMES

Name: CROW_BACKEND_PODMAN_VOLUMES
Description: Additional volumes to mount in Podman containers.
Default: none

Resource Limits

BACKEND_PODMAN_LIMIT_MEM

Name: CROW_BACKEND_PODMAN_LIMIT_MEM
Description: Whether to limit memory usage in Podman containers. No limit is applied if set to 0.
Default: 0

BACKEND_PODMAN_LIMIT_MEM_SWAP

Name: CROW_BACKEND_PODMAN_LIMIT_MEM_SWAP
Description: Whether to limit memory swap usage in Podman containers. No limit is applied if set to 0.
Default: 0

BACKEND_PODMAN_LIMIT_SHM_SIZE

Name: CROW_BACKEND_PODMAN_LIMIT_SHM_SIZE
Description: Whether to limit shared memory size in Podman containers. No limit is applied if set to 0.
Default: 0

BACKEND_PODMAN_LIMIT_CPU_QUOTA

Name: CROW_BACKEND_PODMAN_LIMIT_CPU_QUOTA
Description: Microseconds per CPU quota before throttling takes place. No limit is applied if set to 0.
Default: 0

BACKEND_PODMAN_LIMIT_CPU_SHARES

Name: CROW_BACKEND_PODMAN_LIMIT_CPU_SHARES
Description: CPU shares (relative weight) for Podman containers. No limit is applied if set to 0.
Default: 0

BACKEND_PODMAN_LIMIT_CPU_SET

Name: CROW_BACKEND_PODMAN_LIMIT_CPU_SET
Description: Comma-separated list of specific CPU cores the pipelines are limited to. No limit is applied if set to 0.
Default: none

Proxy Settings

BACKEND_HTTP_PROXY

Name: CROW_BACKEND_HTTP_PROXY
Description: If set, pass the environment variable down as “HTTP_PROXY” to steps.
Default: none

BACKEND_HTTPS_PROXY

Name: CROW_BACKEND_HTTPS_PROXY
Description: If set, pass the environment variable down as “HTTPS_PROXY” to steps.
Default: none

BACKEND_NO_PROXY

Name: CROW_BACKEND_NO_PROXY
Description: If set, pass the environment variable down as “NO_PROXY” to steps.
Default: none

Rootless Podman

The Podman backend supports rootless installations. When CROW_BACKEND_PODMAN_HOST is not set, the backend automatically detects:

Rootful socket: /run/podman/podman.sock
Rootless socket: $XDG_RUNTIME_DIR/podman/podman.sock

Differences from Docker Backend

The Podman backend aims for feature parity with the Docker backend but there are architectural and behavioral differences to be aware of.

Architecture

| | Docker | Podman | | --- | --- | --- | | SDK | Docker Go SDK | Native Podman Go bindings | | Daemon | Long-running daemon (dockerd) | Daemonless — communicates via a socket API | | Rootless | Requires extra setup (rootless mode) | First-class rootless support | | Socket location | /var/run/docker.sock | Auto-detected (rootful or rootless) | | TLS remote access | Supported (CROW_BACKEND_DOCKER_TLS_VERIFY, CROW_BACKEND_DOCKER_CERT) | Not yet supported — local socket only |

Networking

| | Docker | Podman | | --- | --- | --- | | Default network driver | bridge (Linux), nat (Windows) | bridge | | IPv6 | CROW_BACKEND_DOCKER_ENABLE_IPV6 | CROW_BACKEND_PODMAN_ENABLE_IPV6 | | Network creation | Fails if name conflicts | Tolerates “already exists” and reuses |

Log streaming

Docker multiplexes stdout/stderr through the Docker stream protocol and uses stdcopy.StdCopy to demultiplex. Podman streams stdout and stderr over separate channels and tags each line with a 0x01 (stdout) or 0x02 (stderr) prefix byte before writing to the pipe. The end result is the same for users but the internal plumbing differs, which may surface edge-case differences with very large or interleaved log output.

Features not yet available in the Podman backend

Stale resource cleanup — The Docker backend periodically removes orphaned containers, networks, and volumes that outlive a configurable threshold. The Podman backend does not implement this yet.
Remote TLS connections — Docker supports connecting to a remote daemon over TLS. The Podman backend currently only supports local Unix sockets.

Migration checklist

Set CROW_BACKEND=podman on your agent.
Ensure the Podman socket service is running:
- Rootful: systemctl start podman.socket
- Rootless: systemctl --user start podman.socket
Rename any CROW_BACKEND_DOCKER_* environment variables to their CROW_BACKEND_PODMAN_* equivalents (see the table above).
Verify your pipelines pass — most workflows work without changes.