Getting Started

@taskbox/core is the engine that ties a TaskSpec to a runtime adapter and a result. You almost always pair it with a runtime; for the kitchen-sink image shipped with Taskbox, that's @taskbox/podman.

1. Install

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

@taskbox/schemas is a peer-style dependency: same zod instance everywhere keeps TaskboxError and TaskEvent cheap to validate.

2. Check the runtime is healthy

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

const adapter = podman({ pullPolicy: "if-missing" });
const av = await adapter.available();
if (!av.ok) throw new Error("podman unavailable: " + JSON.stringify(av.details));

3. Run a task

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

const result = await runTask(
  {
    tool: "media.downloadSubtitles",
    input: {
      url: "https://youtu.be/jNQXAC9IVRw",
      languages: ["en"],
      format: "vtt",
    },
    network: { mode: "direct" },
  },
  adapter,
  {
    onEvent: (e) => {
      if (e.type === "process.stderr") process.stderr.write(e.data + "\n");
    },
  },
);

console.log(result.ok ? "artifacts" : "error", result.ok ? result.artifacts : result.error);

4. Customize the workspace location

By default, runs land under os.tmpdir()/taskbox-runs/<taskId> and are removed when the task succeeds (or always, on failure).

Set TASKBOX_WORKSPACE_DIR=/path/to/runs to relocate the root.
Set TASKBOX_KEEP_WORKSPACE=1 to suppress cleanup for debugging.
Or pass { root, keep } to createWorkspace if you're driving the bus yourself.

5. Handle errors

Failures come back as a TaskResult with ok: false and a TaskboxError shape. Construct one programmatically when you need to reject from a custom adapter:

import { TaskboxError } from "@taskbox/core";

throw new TaskboxError({
  code: "E_RUNTIME_UNAVAILABLE",
  category: "runtime",
  message: "no podman socket",
  retryable: false,
});