pip install blobhub-worker (Python 3.12 or later); the worker’s Introduction has the install
and a first run, and its Concepts the model behind it.
The three coding agents
The worker runs Claude Code and Codex through the libraries their vendors publish, and Antigravity by starting its binary and reading its output. No other agent runs on it. Their command-line tools are not bundled: each one you use must already be installed and signed in on the machine, and the worker checks only that its command is onPATH.
A thread’s metadata names which of the three runs it. The rest of the agent’s settings, its executable, model, effort
and permissions, resolve one field at a time, most specific first: the thread’s own value, then the worker’s
configuration for that agent, then a built-in default. The built-in default for permissions is approval, so until
someone says otherwise, an agent asks a person before each gated call. Configuration has
the worker’s side, and Policies & approvals the three postures.
Workers and profiles
A worker acts for one identity, the one its profile names. A profile is a named API key and the API it belongs to, stored in~/.blobhub/credentials.yaml, the file the CLI uses too. On the worker it also names the local state that
belongs to that identity: the sessions it watches, how far it has read each thread, its configuration, logs and lock.
One worker runs per profile, and a second copy on the same profile is refused, while workers on different profiles
run side by side on one machine. Authentication and profiles covers both.
Run a worker on a service account’s key rather than your own. The worker takes every
post made by its own identity for its own output and never hands it to the agent, so a person posting under that
identity is never heard. On an account of its own, everything the worker posts is attributed to that account, and its
access is granted and taken away by membership, like any member’s.
Each worker reads a config.yaml that lists its sections, each attached to one session or to one prefix of that
session’s objects. The same file caps the number of agents running at once, and a thread that finds no free slot
waits for one. After a restart, the worker resumes the threads it was working. blobhub-worker start --tui shows
all of it on a dashboard; without --tui the worker runs headless and writes structured logs.
Threads as the channel
A worker attaches to a session by claiming aworker object in it, then watches the session’s threads. Work moves
through one field on a thread’s envelope metadata, state. You set it to pending to hand the thread to an agent,
with the folder the agent should work in and the agent to run beside it. The worker writes back active once it picks
the thread up, and failed if the run cannot go on; it never writes completed. Ending the agent’s part is yours:
set completed or failed, and set a failed thread back to pending to try again.
The hand-off is a write to the thread’s envelope, over the API or from a workflow’s code, which is how
Missions hands its coding steps to agents. Once a thread is active, talking to the agent is
ordinary posting: a person in a playground’s thread widget, a workflow and the agent all add items to the same
thread. Threads & objects covers threads themselves.
While a thread is active, the worker runs one turn at a time. Whatever others posted since the last turn is
coalesced into one prompt. The agent’s text, tool calls, tool results and status are posted back as thread items as
the agent produces them, and the worker moves its place in the thread forward only when a turn completes, so nothing
is counted twice. Session agent harness walks through the loop, and
Thread items has each item’s shape.
When the agent needs a person in the middle of a turn, for a call its permissions gate or, on Claude Code, a question
of its own, the request is posted as an item and, by default, the turn waits where it is. The agent process stays up,
the call is held, and an answer posted to the thread releases it, whether that takes a minute or a week; the wait
gives up its agent slot and does not count against the turn’s time. If the worker restarts meanwhile, the question
survives, and its answer resumes the same agent session.
Interactive prompts covers how an answer is matched to its
question.
Files in and out
Files ride the same items. Before a turn starts, the worker fetches every file the turn’s new items reference into an inbox inside the agent’s work folder, in a directory of that turn’s own, so one turn’s attachments never collide with another’s. Claude Code and Codex receive images natively, each at its place in the message, and other files by path; Antigravity, whose input takes text only, gets every file as a path at the same place. A file that cannot be fetched does not fail the turn: it is reported on an item of its own. Going the other way, a thread can name an outbox, a folder inside the work folder. At the end of each turn, whatever the agent left there is uploaded as new session files, within the size cap and content types every session file is held to, and an item carries a file block for each one, the same reference a person’s attachment carries. Threads & objects covers session files.Where it runs
The worker runs on your infrastructure, a laptop, a server or a container, as an ordinary API client with no standing of its own. It calls the REST API over HTTPS with its key and polls the session for new events at an adaptive rate, so it needs no inbound connection and the platform holds no channel open to it. An agent starts in its thread’s work folder, but that folder is a starting directory, not a boundary the worker draws. The agent runs with the reach of the operating-system user the worker runs as, and what holds it back is its permission posture:approval puts a person in front of each gated call, guarded lets a policy decide most of them,
and autonomous gates nothing. Only Codex, under approval or guarded, also runs inside an operating-system
sandbox; on Claude Code and Antigravity the worker’s gate is the whole guardrail.
Policies & approvals covers the postures, the policies and their limits.