> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents & workers
> Claude Code, Codex and Antigravity on your own machines, working through the same threads as everything else.
export const Scope = ({type, href}) => {
const scopes = {
workflow: ['the ', 'Workflow', ' blob type', '/blob-types/introduction#workflow'],
scheduler: ['the ', 'Scheduler', ' blob type', '/blob-types/scheduler/overview'],
onnx: ['the ', 'ONNX Model', ' blob type', '/blob-types/introduction#onnx'],
worker: ['', 'blobhub-worker', ', which runs on your machines', '/worker/introduction']
};
const scope = scopes[type];
if (!scope) {
return Unknown scope: {type}
;
}
return
Provided by {scope[0]}{scope[1]}{scope[2]}. ยท Reference
;
};
export const Shot = ({src, alt, caption}) =>
$/,)
;
blobhub-worker is a process you run on your own machine that runs coding agents against a session's threads. You hand
it a thread, the agent works in a folder on that machine, and its messages, tool calls and questions come back to the
thread as items, beside everything else posted there. It runs three agents: Claude Code, Codex and Antigravity.
The worker is how agents BlobHub did not build join the work: they run on your hardware, next to your code and tools,
and answer through the same threads, into the same record, as everything else. Install it with
`pip install blobhub-worker` (Python 3.12 or later); the worker's [Introduction](/worker/introduction) has the install
and a first run, and its [Concepts](/worker/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 on `PATH`.
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](/worker/configuration) has
the worker's side, and [Policies & approvals](/general/policies-and-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](/worker/auth) covers both.
Run a worker on a [service account](/general/service-accounts)'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 a `worker` 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](/general/apps) 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](/general/threads-and-objects#threads) 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](/worker/session-agent-harness/overview) walks through the loop, and
[Thread items](/worker/session-agent-harness/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](/worker/session-agent-harness/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](/general/threads-and-objects#files) 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](/general/policies-and-approvals) covers the postures, the policies and their limits.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.