podman-ts

mintlify_docs

TypeScript/Bun bindings for the Podman RESTful API (libpod). This library provides a high-level, type-safe interface for managing containers, images, pods, networks, volumes, secrets, manifests, quadlets, and more.

Runtime: The library uses Bun-native APIs (Bun.spawn, Bun.file, Unix-socket fetch). Install and run with Bun (bun >=1.0). package.json also declares Node >= 18 for tooling compatibility; execution is intended under Bun.

npm install @pratyay360/podman-ts
# or
bun add @pratyay360/podman-ts

import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();

const containers = await client.containers.list({ all: true });
for (const container of containers) {
  console.log(`${container.id} - ${container.name} (${container.status})`);
}

const image = await client.images.pull("docker.io/library/nginx:latest");
console.log(`Pulled: ${image.tags.join(", ")}`);

const container = await client.containers.create({
  image: "nginx",
  name: "my-nginx",
  portMappings: [{ container_port: 80, host_port: 8080 }],
});
await container.start();

const logs = await container.logs();
console.log(logs);

await container.stop();
await container.remove();

const client = new PodmanClient({
  baseUrl: "http+unix:///run/user/1000/podman/podman.sock",
  connection: "my-remote-machine",
  version: "5.0.0",
  timeout: 5000,
});

The client exposes client.api (APIClient) for arbitrary libpod/compat requests. Convenience getters return promises: client.ping, client.version, client.info, client.df. Call client.close() (or use using / Symbol.dispose) when you want a disposal hook; today it is a no-op.

If baseUrl is omitted:

1. If connection is set, that named service URL is used.
2. Otherwise, PodmanConfig is read: if the active service is a Podman machine, its URL is used.
3. Otherwise the local Unix socket is used (/run/podman/podman.sock as root, or $XDG_RUNTIME_DIR/podman/podman.sock for rootless).

Environment variables CONTAINER_HOST and DOCKER_HOST are not read by new PodmanClient().

Use the factory so CONTAINER_HOST or DOCKER_HOST wins over the default socket:

import { fromEnv, PodmanClient } from "@pratyay360/podman-ts";

const client = fromEnv();
// same as:
const same = PodmanClient.fromEnv();

Podman’s HTTP surface is large (see the project’s swagger-latest.yaml for the full spec). This package implements a curated subset focused on common container workflows. For operations that are not wrapped yet, use client.api (get, post, put, patch, delete, head) with libpod paths (default prefix /v{version}/libpod) or compatible: true for /v{version}/compat (e.g. registry /auth for system.login).

Container instance: start, stop, restart, kill, pause, unpause, wait, remove, rename, inspect (GET json), logs (string or AsyncIterable when stream: true), top, diff, commit, reload.

Image instance: history, tag, remove, reload. Use get() / reload() for fresh inspect data (there is no separate inspect() on the instance).

Pod instance: start, stop, restart, kill, pause, unpause, remove, top, reload. There is no inspect() method; use reload() or pods.get().

Network instance: connect, disconnect, remove, reload.

Volume instance: inspect, remove, reload.

Secret instance: remove.

Manifest instance: add, push, remove (by digest), reload.

Quadlet instance: getContents, delete.

There is no separate stream() method; use for await … of client.events.list().

const logStream = await container.logs({ stream: true, follow: true });
for await (const chunk of logStream) {
  process.stdout.write(chunk + "\n");
}

for await (const line of client.events.list({ decode: true })) {
  const event = line as Record<string, unknown>;
  console.log(event);
}

import { NotFound, ImageNotFound, APIError } from "@pratyay360/podman-ts";

try {
  await client.images.get("non-existent-image");
} catch (err) {
  if (err instanceof ImageNotFound) {
    // missing image
  } else if (err instanceof APIError) {
    console.error(`${err.statusCode}: ${err.message}`);
  }
}

Exported error classes include PodmanError, APIError, NotFound, ImageNotFound, BuildError, ContainerError, InvalidArgument, StreamParseError.

import { DockerClient } from "@pratyay360/podman-ts";
const client = new DockerClient();

For custom tooling you can import APIClient, APIResponse, helpers (prepareFilters, prepareBody, encodeAuthHeader, …), PodmanConfig, IPAMConfig / IPAMPool, jsonStream / lineStream, base Manager / PodmanResource, and version constants (VERSION, API_VERSION, COMPATIBLE_VERSION) from the package entry (src/index.ts).

bun install
bun run lint
bun run typecheck
bun test
bun run build

Apache-2.0