Managing containers with podman-ts

ContainersManager is the primary interface for working with Podman containers. It is accessible via client.containers on any PodmanClient instance and provides methods for the full container lifecycle — from creation through removal — as well as access to Container instances with their own per-container operations.

ContainersManager methods

list

list(options?: ContainerListOptions): Promise<Container[]>

List containers. By default only running containers are returned.

options.all

boolean

Include stopped containers. Equivalent to podman ps -a.

options.limit

number

Maximum number of containers to return.

options.filters

Record<string, string | string[]>

Key/value filters applied server-side (e.g. { status: "running", label: "app=web" }).

options.since

string

Return containers created after this container ID/name.

options.before

string

Return containers created before this container ID/name.

get

get(id: string, options?: { compatible?: boolean }): Promise<Container>

Load a container by its ID or name. Throws NotFound if the container does not exist.

options.compatible

boolean

Use the Docker-compatible endpoint (/compat) instead of libpod.

create

create(opts: ContainerCreateOptions): Promise<Container>

Create a container and return a Container instance. The container is not started — call container.start() after creation. Throws ImageNotFound if the image is not present locally. Key fields in ContainerCreateOptions:

opts.image

string

required

Image reference (e.g. "docker.io/library/nginx:latest").

opts.name

string

Container name.

opts.command

string | string[]

Override the image’s default command.

opts.env

Record<string, string> | string[]

Environment variables as a dict or ["KEY=value"] list.

opts.ports

Record<string, unknown>

Port mappings as { "80/tcp": 8080 }. The key is containerPort/protocol; the value is the host port.

opts.volumes

Record<string, { bind: string; mode?: string }>

Bind mounts as { "/host/path": { bind: "/container/path", mode: "ro" } }.

opts.labels

Record<string, string>

Container labels.

opts.privileged

boolean

Run in privileged mode.

opts.remove

boolean

Automatically remove the container when it exits.

opts.restartPolicy

{ Name: string; MaximumRetryCount?: number }

Restart policy, e.g. { Name: "on-failure", MaximumRetryCount: 3 }.

opts.workingDir

string

Working directory inside the container.

opts.user

string | number

User to run the container as.

See ContainerCreateOptions in src/domain/containers_create.ts for the full list of accepted fields.

run

run(
  image: string,
  command?: string | string[],
  options?: RunOptions
): Promise<Container | string>

Create, start, and wait for a container in one call. This is the equivalent of podman run.

If the image is not found locally, it is pulled automatically (policy: "missing").
On exit code 0, returns the captured stdout as a string.
On non-zero exit, throws ContainerError with the exit code.
With detach: true, starts the container and returns the Container instance immediately.

RunOptions extends ContainerCreateOptions (minus image) with:

options.stdout

boolean

default:"true"

Capture stdout in the returned log string.

options.stderr

boolean

default:"false"

Capture stderr in the returned log string.

options.remove

boolean

default:"false"

Remove the container after it exits.

options.detach

boolean

default:"false"

Return the Container immediately without waiting.

options.platform

string

Platform override when pulling the image (e.g. "linux/amd64").

options.authConfig

Record<string, string>

Auth credentials forwarded to the pull call.

exists

exists(id: string): Promise<boolean>

Return true if a container with the given ID or name exists, false otherwise.

remove

remove(id: string, options?: {
  force?: boolean;
  volumes?: boolean;
  depend?: boolean;
  ignore?: boolean;
  timeout?: number;
}): Promise<void>

Remove a container by ID or name.

options.force

boolean

Stop and remove a running container.

options.volumes

boolean

Also remove anonymous volumes attached to the container.

prune

prune(filters?: Record<string, string>): Promise<Record<string, unknown>>

Remove all stopped containers. Optionally pass filters to narrow the set (e.g. { until: "24h" }). Returns a summary of removed containers and reclaimed space.

Container instance methods

A Container object is returned by create(), run() (when detached), get(), and list(). It exposes these methods:

Lifecycle

Method	Signature	Description
`start`	`(): Promise<void>`	Start the container.
`stop`	`(options?: { timeout?: number }): Promise<void>`	Stop the container, with optional grace period in seconds.
`restart`	`(options?: { timeout?: number }): Promise<void>`	Restart the container.
`kill`	`(signal?: string \| number): Promise<void>`	Send a signal to the container (default `SIGKILL`).
`pause`	`(): Promise<void>`	Pause all processes in the container.
`unpause`	`(): Promise<void>`	Unpause a paused container.
`wait`	`(options?: { condition?: string \| string[]; interval?: string }): Promise<number>`	Block until the container reaches `condition`. Returns the exit code.
`remove`	`(options?: { force?: boolean; volumes?: boolean; depend?: boolean }): Promise<void>`	Remove the container.

Inspection and metadata

Method	Signature	Description
`inspect`	`(options?: { size?: boolean }): Promise<Record<string, unknown>>`	Return the full JSON inspect object from the Podman API.
`rename`	`(newName: string): Promise<void>`	Rename the container.
`reload`	`(): Promise<void>`	Refresh `container.attrs` from the API.
`top`	`(options?: { psArgs?: string }): Promise<Record<string, unknown>>`	List running processes inside the container.
`diff`	`(options?: { parent?: string; diffType?: "all" \| "container" \| "image" }): Promise<Array<Record<string, unknown>>>`	Show filesystem changes relative to the image.

Logs

logs(opts?: LogOptions): Promise<string>
logs(opts: LogOptions & { stream: true }): Promise<AsyncIterable<string>>

Return container logs. When stream: true is set, the return type changes to AsyncIterable<string> for line-by-line streaming.

opts.stdout

boolean

default:"true"

Include stdout.

opts.stderr

boolean

default:"true"

Include stderr.

opts.follow

boolean

default:"false"

Keep the stream open and follow new output (requires stream: true).

opts.since

string | number

Only return logs since this timestamp or relative duration.

opts.until

string | number

Only return logs up to this timestamp.

opts.tail

number | "all"

Number of lines from the end of the log to return.

Commit

commit(options?: {
  repository?: string;
  tag?: string;
  message?: string;
  author?: string;
}): Promise<Record<string, unknown>>

Create a new image from the container’s current filesystem state.

Code examples

List all containers

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

const client = new PodmanClient();

const containers = await client.containers.list({ all: true });
for (const c of containers) {
  console.log(c.id, c.name, c.status);
}

Create and start a container with port mappings

const container = await client.containers.create({
  image: "docker.io/library/nginx:latest",
  name: "my-nginx",
  ports: { "80/tcp": 8080 },
  labels: { app: "web" },
});

await container.start();
console.log("Container started:", container.id);

Stream logs from a running container

const container = await client.containers.get("my-nginx");

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

Run a one-shot container

// Runs the container, waits for exit, returns stdout.
// Throws ContainerError if exit code is non-zero.
const output = await client.containers.run(
  "docker.io/library/alpine:latest",
  ["echo", "hello from podman-ts"],
  { remove: true }
);
console.log(output); // "hello from podman-ts"

Remove stopped containers

const result = await client.containers.prune({ until: "24h" });
console.log("Pruned:", result);

Get Started

Core Concepts

Resource Managers

Advanced

Managing containers with podman-ts

ContainersManager methods

list

get

create

run

exists

remove

prune

Container instance methods

Lifecycle

Inspection and metadata

Logs

Commit

Code examples

List all containers

Create and start a container with port mappings

Stream logs from a running container

Run a one-shot container

Remove stopped containers

Build docs developers (and LLMs) love

Get Started

Core Concepts

Resource Managers

Advanced

Documentation Index

​ContainersManager methods

​list

​get

​create

​run

​exists

​remove

​prune

​Container instance methods

​Lifecycle

​Inspection and metadata

​Logs

​Commit

​Code examples

​List all containers

​Create and start a container with port mappings

​Stream logs from a running container

​Run a one-shot container

​Remove stopped containers

Build docs developers (and LLMs) love

ContainersManager methods

list

get

create

run

exists

remove

prune

Container instance methods

Lifecycle

Inspection and metadata

Logs

Commit

Code examples

List all containers

Create and start a container with port mappings

Stream logs from a running container

Run a one-shot container

Remove stopped containers