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.

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

2. Install the CLI

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

3. Doctor

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

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

5. Run a tool

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

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