Getting Started

1. Install

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

You only ever interact with @taskbox/tools directly; the others come along as transitive dependencies but stay accessible if you need them.

2. Wire a runtime

import { createTaskbox } from "@taskbox/tools";
import { podman } from "@taskbox/podman";

const tbx = createTaskbox({
  runtime: podman({ pullPolicy: "if-missing" }),
  // optional defaults applied to every call
  defaults: {
    timeoutMs: 60_000,
    networkMode: "direct",
  },
});

3. Sanity-check the runtime + image

const ready = await tbx.prepare();
// {
//   runtime: "podman",
//   image: { ref: "taskbox/kitchen-sink:0.1.0", digest: "sha256:..." },
//   rootless: true,
//   version: "5.x.x",
// }

prepare() throws TaskboxError({ code: "E_RUNTIME_UNAVAILABLE" }) if the runtime adapter reports available().ok === false.

4. Call a tool

const result = await tbx.media.downloadSubtitles(
  {
    url: "https://youtu.be/jNQXAC9IVRw",
    languages: ["en", "de"],
    format: "srt",
    auto: false,
    outputDir: "/tmp/subs",
  },
  {
    onEvent: (e) => {
      if (e.type === "task.failed") console.error(e.error.message);
    },
  },
);

A proxy field on the input flips network mode to "proxy" automatically so tasks behind a corporate egress reuse the same code path.

5. Drop down to `runTask` when needed

const raw = await tbx.runTask({
  tool: "media.downloadSubtitles",
  input: { url: "https://...", languages: ["en"] },
  network: { mode: "direct" },
});

tbx.runTask accepts an unknown spec, validates it via TaskSpecSchema, and returns a typed TaskResult. Use it when you're forwarding a spec from a queue, IPC, or another process.