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.

podman-ts is a high-level, type-safe TypeScript SDK for Podman’s libpod REST API. This page explains what the library does, what it covers, and how it fits into the Podman ecosystem.

​
What is podman-ts?

Podman is a daemonless, rootless container engine compatible with the OCI standard. It exposes a local HTTP API (libpod) over a Unix socket or TCP, giving you full programmatic control over containers, images, pods, networks, volumes, and more. podman-ts wraps that API in idiomatic TypeScript. Instead of constructing raw HTTP requests, you work with typed resource managers and object instances — client.containers.create(...), container.start(), container.logs() — while the SDK handles serialisation, error mapping, and socket communication for you. The library is built on Bun-native APIs (Bun.fetch with Unix socket support, Bun.spawn for tar operations) and is intended to run under Bun >= 1.0.

​
Key features

Type-safe TypeScript bindings

Every request and response is fully typed. TypeScript catches mismatches at compile time before they reach Podman.

Bun-native connections

Connects over Unix sockets or TCP using Bun’s native fetch implementation — no extra HTTP client dependencies.

Resource managers

Dedicated managers for containers, images, pods, networks, volumes, secrets, manifests, quadlets, events, system, kube, and artifacts.

Streaming via async iterators

Streaming logs, events, and other continuous responses are consumed with standard for await...of loops.

Kubernetes YAML support

client.kube lets you generate Kubernetes YAML from Podman resources and apply YAML manifests directly.

Docker-compatible alias

Import DockerClient as a drop-in alias for PodmanClient when porting code from Docker SDK patterns.

Environment-based connection

Use fromEnv() or PodmanClient.fromEnv() to resolve the service URL from CONTAINER_HOST or DOCKER_HOST.

Low-level escape hatch

client.api exposes get, post, put, patch, delete, and head for any libpod path not covered by the high-level managers.

​
API coverage

Podman’s HTTP surface is large — the full spec lives in the project’s swagger-latest.yaml. podman-ts implements a curated subset focused on common container workflows. For operations that are not wrapped yet, use client.api directly with libpod paths: 
// Call any libpod endpoint not covered by the high-level managers
const res = await client.api.get("/containers/json", { params: { all: true } });
res.raiseForStatus();

// Use compatible: true for Docker-compatible (/compat) endpoints
await client.api.post("/auth", {
  data: { username: "user", password: "pass" },
  compatible: true,
});
The default path prefix is /v{version}/libpod. Pass compatible: true to target /v{version}/compat instead (for example, registry /auth used by system.login).

​
License

podman-ts is released under the Apache-2.0 license.

Build docs developers (and LLMs) love

Get started for freeTalk to us