# API

> @taskbox/podman public exports.

Source: https://taskbox.n.yatsyk.com/docs/podman/api

# API

## Adapter factory

| Export                 | Signature                                                                                      | Summary                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `podman`               | `(opts?: PodmanAdapterOptions) => RuntimeAdapter`                                              | Returns a `RuntimeAdapter` (from `@taskbox/core`) that drives rootless Podman. |
| `PodmanAdapterOptions` | `{ binary?: string; defaultImage?: string; pullPolicy?: "always" \| "if-missing" \| "never" }` | Override the binary path, image ref, and pull behaviour.                       |

## RuntimeAdapter shape

The returned adapter implements the `RuntimeAdapter` contract from
`@taskbox/core`:

| Method         | Signature                                                                            | Summary                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `available`    | `() => Promise<{ ok: boolean; details?: { rootless?, version?, stderr?, error? } }>` | Calls `podman info`; reports rootless flag and version.                                                                         |
| `prepareImage` | `(ref: string) => Promise<{ digest?: string }>`                                      | Honours `pullPolicy`. Throws `TaskboxError({ code: "E_IMAGE_PULL_FAILED" })` on pull failure.                                   |
| `runTask`      | `({ spec, workspace, bus, signal? }) => Promise<{ exitCode, durationMs }>`           | Spawns `podman run` with bind mounts, network mode, and resource flags applied; emits `image.prepare.*` and `process.*` events. |

## Behaviour notes

* **Container args:** `--rm --userns=keep-id`, `--network=none` when
  `spec.network.mode === "none"`, plus `--cpus`/`--memory` from
  `spec.resources`.
* **Mounts:** `workspace.inputDir → /in:ro,Z`, `workspace.outputDir → /out:Z`.
* **Stderr parsing:** each line is parsed as JSON; if it matches
  `TaskEventSchema`, it's re-emitted as a structured event, otherwise it
  becomes a `process.stderr` event verbatim.
* **Cancellation:** `signal.abort()` triggers `SIGTERM`, then `SIGKILL` after
  2 s. `spec.resources.timeoutMs` uses the same path and surfaces as
  `TaskboxError({ code: "E_TIMEOUT", retryable: true })`.

See the generated [JSDoc reference](/docs/podman/jsdoc) for the full surface.