Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pratyay360/podman-ts/llms.txt

Use this file to discover all available pages before exploring further.

PodmanClient is the top-level entry point for the podman-ts SDK. It holds a lazily-initialized set of resource managers and a public api property that exposes the underlying APIClient for raw HTTP calls. You create one instance per application and reuse it across requests. 
import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();
const containers = await client.containers.list({ all: true });
await client.close();

​
Constructor

new PodmanClient(options?: PodmanClientOptions): PodmanClient
Creates a new client. When no baseUrl or connection is provided, the client reads the active service from containers.conf. If the active service is a Podman machine, its URL is used; otherwise the local Unix socket is used.
​
baseUrl
string
Full URL to the Podman service, e.g. "http+unix:///run/podman/podman.sock" or "tcp://127.0.0.1:8080". When set, connection is ignored.
​
connection
string
Named connection from containers.conf or podman-connections.json. Ignored if baseUrl is provided.
​
version
string
API version prefix override. Default: "v5.0.0".
​
timeout
number
Request timeout in milliseconds. When omitted, requests do not time out.
​
identity
string
Path to an SSH identity file. Used when connecting over ssh://.

​
Static factory methods

​
PodmanClient.fromEnv

static fromEnv(options?: Omit<PodmanClientOptions, "baseUrl">): PodmanClient
Creates a PodmanClient whose base URL is read from the environment. Checks CONTAINER_HOST, then DOCKER_HOST, then falls back to the local Unix socket. 
const client = PodmanClient.fromEnv({ timeout: 5000 });

​
fromEnv (exported function)

function fromEnv(options?: Omit<PodmanClientOptions, "baseUrl">): PodmanClient
Module-level shorthand that calls PodmanClient.fromEnv(). Mirrors the Python SDK convention. 
import { fromEnv } from "@pratyay360/podman-ts";

const client = fromEnv();

​
DockerClient alias

export const DockerClient = PodmanClient;
DockerClient is a named export that aliases PodmanClient. It exists for Docker SDK compatibility and is identical in every way.

​
Public property

PropertyTypeDescription
apiAPIClientThe underlying low-level HTTP client. Use it to make requests not covered by the resource managers.

​
Resource manager getters

Each getter is lazily initialized — the manager instance is created on first access and reused on subsequent accesses.
GetterTypeDescription
containersContainersManagerCreate, list, inspect, start, stop, remove, and exec into containers.
imagesImagesManagerPull, push, build, list, tag, and remove images.
networksNetworksManagerCreate, list, inspect, connect, and remove networks.
volumesVolumesManagerCreate, list, inspect, and remove volumes.
podsPodsManagerCreate, list, inspect, start, stop, and remove pods.
secretsSecretsManagerCreate, list, inspect, and remove secrets.
manifestsManifestsManagerCreate and manage image manifest lists.
quadletsQuadletsManagerRead and write Quadlet unit files on the host.
eventsEventsManagerStream or list Podman events.
systemSystemManagerPing, version, info, df, and login operations.
kubeKubeManagerGenerate and apply Kubernetes YAML; generate systemd units.
artifactsArtifactsManagerPush, pull, and manage OCI artifacts.

​
Convenience properties

These properties delegate to SystemManager and return Promises. They are shorthand for the equivalent client.system.*() calls.
PropertyReturn typeEquivalent to
pingPromise<boolean>client.system.ping()
versionPromise<Record<string, unknown>>client.system.version()
infoPromise<Record<string, unknown>>client.system.info()
dfPromise<Record<string, unknown>>client.system.df()

​
Instance methods

​
close

close(): void
Releases any resources held by the client. Currently a no-op because Bun’s native fetch does not maintain a persistent connection pool. Call it for forward compatibility or use the using declaration below.

​
[Symbol.dispose]

[Symbol.dispose](): void
Implements the TC39 Explicit Resource Management protocol. Calls close() automatically when the client goes out of scope inside a using block. 
using client = new PodmanClient();
const info = await client.info;
// close() is called automatically here

Build docs developers (and LLMs) love

Get started for freeTalk to us