# Getting Started

> First call into @taskbox/podman.

Source: https://taskbox.n.yatsyk.com/docs/podman/getting-started

# Getting Started

`@taskbox/podman` is the only runtime adapter shipped today. It expects a
Podman binary on `$PATH` and the kitchen-sink image (or your own) available
locally — or pullable, depending on `pullPolicy`.

## 1. Install Podman

Use whichever your distro prefers — `apt`, `brew`, `mise registry podman`.
Verify rootless mode is healthy:

```bash
podman info --format '{{.Host.Security.Rootless}}'
# → true
```

## 2. Install the adapter

```bash
npm i @taskbox/podman @taskbox/core @taskbox/schemas
```

## 3. Smoke-test the runtime

```ts
import { podman } from "@taskbox/podman";

const adapter = podman();
const av = await adapter.available();
console.log(av);
// { ok: true, details: { rootless: true, version: "5.x.x" } }
```

## 4. Pull the image up front

```ts
const { digest } = await adapter.prepareImage("taskbox/kitchen-sink:0.1.0");
console.log("image digest:", digest);
```

## 5. Run a task

```ts
import { runTask } from "@taskbox/core";

const result = await runTask(
  {
    tool: "media.downloadSubtitles",
    input: { url: "https://youtu.be/jNQXAC9IVRw", languages: ["en"] },
    network: { mode: "direct" },
    runtime: { backend: "podman" },
    resources: { timeoutMs: 60_000 },
  },
  adapter,
);
```

The adapter applies `--cpus` / `--memory` from `spec.resources` and
`--network=none` when `spec.network.mode === "none"`. For `mode: "proxy"`,
the proxy URL is expanded into `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` env
vars (and lowercase variants) inside the container.

## 6. Cancel a long-running task

```ts
const ac = new AbortController();
setTimeout(() => ac.abort(), 5_000);

await runTask(spec, adapter, { signal: ac.signal });
```

The adapter sends `SIGTERM`, then `SIGKILL` after 2 s if the container hasn't
exited. A `spec.resources.timeoutMs` is enforced the same way and surfaces as
`E_TIMEOUT`.