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:

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

2. Install the adapter

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

3. Smoke-test the runtime

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

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

5. Run a task

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

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.