podman

A Dart client for the Podman libpod API over the Podman socket.

This package uses HTTP over Unix sockets and targets libpod endpoints directly, without shelling out to the podman CLI.

Features

• Typed PodmanClient API for system, container, and image operations
• Network lifecycle and connect/disconnect APIs
• Network exists/update/prune APIs
• Volume lifecycle APIs
• Pod lifecycle APIs
• Pod exists/admin/top/stats/prune APIs
• Container runtime helpers (wait, healthStatus, exec, stats)
• Container admin APIs (kill/pause/unpause/top/init/rename/update/mount/archive)
• Container checkpoint/restore APIs (including archive export/import helpers)
• System maintenance APIs (system/df, system/check, system/prune)
• Typed events API with reconnecting watch stream
• Unix-socket transport (UnixSocketPodmanTransport)
• Libpod API-first implementation (no Docker-compat fallback path)
• Focused option and model types
• Testable transport abstraction for deterministic unit tests

Installation

dart pub add podman

Quick Start

import 'package:podman/podman.dart';

Future<void> main() async {
  final client = PodmanClient();
  final version = await client.version();
  print('Podman server: ${version.serverVersion}');
  await client.close();
}

Socket Resolution

By default, the transport resolves socket path in this order:

1. PODMAN_SOCKET
2. $XDG_RUNTIME_DIR/podman/podman.sock
3. /run/user/$UID/podman/podman.sock
4. /run/podman/podman.sock

You can override via:

final client = PodmanClient(socketPath: '/custom/path/podman.sock');

Examples

• example/version_info_example.dart
• example/list_containers_example.dart
• example/pull_and_run_example.dart
• example/inspect_container_example.dart
• example/secrets_workflow_example.dart
• example/manifest_workflow_example.dart
• example/artifact_workflow_example.dart
• example/generate_assets_example.dart
• example/play_kube_file_example.dart
• example/system_maintenance_example.dart
• example/checkpoint_restore_example.dart

Copy/paste command guide:

• doc/examples.md

Testing Backends

Default tests use a fake transport for deterministic unit coverage:

melos run test

Local integration tests can run against your local Podman socket:

melos run test:integration

Optional env vars:

• PODMAN_TEST_SOCKET: override socket path for local tests
• PODMAN_LOCAL_TESTS=1: alternate way to enable local tests