Introduction - BlobHub

The BlobHub Worker is a standalone process that runs on your machine, authenticates to BlobHub with an API key, and runs work declared in a local config file. Each entry in the config is a section, and each section has a job_type that decides how the worker handles it. The worker introduces no new BlobHub backend endpoints — every job type speaks the existing BlobHub REST and WebSocket APIs as the user whose API key the worker carries.

Install

pipx install blobhub-worker

Requires Python 3.12+. To upgrade later:

pipx upgrade blobhub-worker

The agent CLIs are separate

The worker drives coding agents; it does not ship them. A session_agent_harness section needs the CLI for whichever agent.type its threads use already installed on the host and already signed in:

`agent.type`	CLI	Notes
`claude_code`	`claude`	Claude Code.
`codex`	`codex`	OpenAI Codex.
`antigravity`	`agy`	Google’s Antigravity CLI — a standalone Go binary, installed and updated on its own. Authentication is a one-time interactive browser sign-in per machine; there is no `agy login` and nothing to put in `config.yaml`.

The worker checks only that the command resolves on PATH. A missing one fails the thread with AGENT_EXECUTABLE_NOT_FOUND; an installed-but-unauthenticated one passes that check and then stalls the turn instead — see Session Agent Harness → Reference.

Quickstart

# 1. Store credentials and validate your identity against /v1/users/me.
blobhub-worker login

# 2. Edit your config to declare one or more sections.
$EDITOR ~/.blobhub-worker/profiles/default/config.yaml

# 3. Run the worker (headless or with the live dashboard).
blobhub-worker start --tui

The minimum config is one section that declares a name and a job_type, plus whatever fields that job type requires. The Configuration page is the complete config.yaml reference.

The live dashboard

Run blobhub-worker start --tui for a live, read-only view of every section and thread. The dashboard reflects what the worker is doing — you drive threads from the BlobHub web UI, not from here.

blobhub-worker --tui dashboard — The `--tui` dashboard — one panel per section, plus a recent-errors strip.

The header shows the worker version, the user it acts as, the instance id, the clock, and how many agent slots are busy (3/10 agents).
Each section is its own panel titled session_agent_harness · <name>, listing its threads with State, Agent, the resumable Session id, and the Last Event. The └ line shows the resolved model · effort · perm; the selected thread is highlighted.
State is color-coded live: active (turn) / active (idle) green, pending yellow, completed dim, failed red.
recent errors collects the latest warnings and failures. Press q for a graceful shutdown.

What’s in this section

The pages in Overview describe the worker as a product, independent of any specific job type:

Concepts — the mental model: process, sections, job types, sessions, threads, and agents.
blobhub-worker login, blobhub-worker start — CLI reference.
Configuration — the complete config.yaml you write.
Reference — process-level exit codes and generic limitations.

The Specification group documents the worker internals — the on-disk and on-wire data model, the per-job-type object notation, and the end-to-end workflows. Start at the Specification introduction. It is organized by job type; v1 ships one job type — Session Agent Harness.

​Install

​The agent CLIs are separate

​Quickstart

​The live dashboard

​What’s in this section

Install

The agent CLIs are separate

Quickstart

The live dashboard

What’s in this section