# Getting Started

> Install tbx and run your first sandboxed task.

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

# Getting Started

## 1. Install Podman

`tbx` shells out to `podman` — install it via your package manager (`apt`,
`brew`, `mise registry podman`). Rootless mode is the supported configuration.

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

## 2. Install the CLI

```bash
npm i -g @taskbox/cli
# or one-shot
npx @taskbox/cli doctor
```

## 3. Doctor

```bash
tbx doctor
# → JSON with runtime, image ref, podman version
```

`doctor` calls `createTaskbox(...).prepare()` under the hood. A non-zero exit
maps to one of:

* `3` — runtime unavailable (`E_RUNTIME_UNAVAILABLE`)
* `4` — image pull failed (`E_IMAGE_PULL_FAILED`)
* `1` — anything else

## 4. Prepare the image

```bash
tbx prepare
# → pulls taskbox/kitchen-sink:0.1.0 if missing, prints digest
```

## 5. Run a tool

```bash
tbx media subtitles https://youtu.be/jNQXAC9IVRw \
  --languages en,de \
  --format srt \
  --auto \
  --output-dir /tmp/subs \
  --timeout 60s
```

By default the final `TaskResult` is pretty-printed JSON on stdout. Add
`--jsonl` to stream every `TaskEvent` (one per line) as the task progresses,
followed by the final result on its own line.

## 6. Behind a proxy

```bash
tbx media subtitles https://youtu.be/jNQXAC9IVRw \
  --proxy http://proxy.lan:3128 \
  --proxy-type http
```

`--proxy URL` flips the spec's `network.mode` to `"proxy"` and the proxy URL
is expanded to `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` inside the container.
`--no-proxy` opts out even if `$HTTPS_PROXY` is set in your shell.

## 7. Exit codes

| Code | Meaning                                               |
| ---- | ----------------------------------------------------- |
| `0`  | success                                               |
| `1`  | generic failure                                       |
| `2`  | schema invalid (`E_SCHEMA_INVALID`)                   |
| `3`  | runtime unavailable                                   |
| `4`  | image pull failed                                     |
| `5`  | timeout                                               |
| `7`  | proxy / network failure                               |
| `9`  | tool produced no `result.json` (`E_ARTIFACT_MISSING`) |
| `10` | tool exited non-zero                                  |