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.

This guide walks you through installing podman-ts, establishing a connection to Podman, and running your first container end-to-end — from pulling an image to removing the stopped container.
Prerequisites: Bun >= 1.0 and a running Podman daemon. Verify with bun --version and podman info.
1

Install the package

Add podman-ts to your project using your preferred package manager.
npm install @pratyay360/podman-ts
2

Connect to Podman

Create a PodmanClient. With no arguments, the client resolves the connection automatically.
import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();
The default resolution order is:
  1. If connection is set, the named service from containers.conf is used.
  2. If the active Podman service is a machine, its URL is used.
  3. Otherwise the local Unix socket is used — /run/podman/podman.sock for root, or $XDG_RUNTIME_DIR/podman/podman.sock for rootless.
To connect to a specific URL or use environment variables instead, see Connecting to Podman.
3

List containers

Retrieve all containers (including stopped ones) and print their IDs, names, and status.
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})`);
}
Pass { all: false } (the default) to list only running containers.
4

Pull an image

Pull an image from a registry using its full reference. The method returns an Image instance with the resolved tags.
import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();

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

Run a container

Create a container, start it, read its logs, then stop and remove it.
import { PodmanClient } from "@pratyay360/podman-ts";

const client = new PodmanClient();

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

// Start it
await container.start();

// Read logs (returns a string by default)
const logs = await container.logs();
console.log(logs);

// Stop and clean up
await container.stop();
await container.remove();
Nginx is now accessible at http://localhost:8080 while the container is running.

​
Next steps

PodmanClient options

Configure the client with a custom URL, named connection, API version, and timeout.

Containers

Full reference for client.containers — create, run, inspect, exec, stream logs, and more.

Images

Pull, push, build, search, and manage images with client.images.

Error handling

Handle typed errors like ImageNotFound, ContainerError, and APIError.

Build docs developers (and LLMs) love

Get started for freeTalk to us