# Getting Started

> First call into @taskbox/core.

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

# 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`](/docs/podman).

## 1. Install

```bash
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

```ts
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

```ts
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:

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

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