BlobHub Worker
BlobHub is the one-stop shop for agentic development. It is a new set of primitives to build against, which makes agents, copilots and the apps that use them easy to design and build — and inherently compatible, because they are all made of the same parts. Agents live and work inside BlobHub, so it is the system of record and action for them: every agent runs inside guardrails the company sets, and everything it does is on the record, written by the work itself. Under the hood, BlobHub is a serverless platform for versioned blob storage with workflow automation: a workflow, a schedule or a model is a typed, versioned blob behind one REST API.
The BlobHub Worker, blobhub-worker, runs Claude Code, Codex and Antigravity on your own machines, inside your
guardrails. It attaches to a workflow session, runs a coding agent for each thread a caller marks pending, and posts
the agent's messages, tool calls and questions back to the thread as items, on the same record as everything else.
Each agent runs under a permission posture: a person approves each gated call, a policy decides most of them, or
nothing is gated. The worker speaks the public REST and WebSocket APIs as the user whose API key it carries, and needs
no inbound connection.
Install
pipx install blobhub-worker
Requires Python 3.12+.
Authenticate
blobhub-worker login # prompts for your API key, validates it, and stores a profile
A profile is an API key, its API URL, and an optional realtime WebSocket URL, kept in
~/.blobhub/credentials.yaml — the same file blobhub-cli
reads and writes, so one login serves both. Select one with --profile, BLOBHUB_PROFILE, or the
file's default:; --api-key / BLOBHUB_API_KEY, --api-url / BLOBHUB_API_URL, and --realtime-url
/ BLOBHUB_REALTIME_URL each outrank it, exactly as in the CLI.
login itself can also run non-interactively and still store a validated profile:
printf '%s' "$API_KEY" | blobhub-worker login --profile ci --api-key-stdin --api-url https://api.blobhub.io/v1
--api-key, --api-url and --realtime-url each accept a literal, --*-stdin (at most one flag per
invocation may read stdin), or --*-env VAR naming an environment variable to read from; --no-input
fails instead of prompting when a value has no source. Prefer --api-key-stdin over a literal
--api-key, which stays visible in ps and shell history.
Each profile also owns a state tree — its own config.yaml, identity.yaml, jobs/ cursors, logs
and single-instance lock — so several workers run side by side on one machine, one per profile:
blobhub-worker start --profile prod &
blobhub-worker start --profile staging & # different tree, different lock, different sessions
A tree is named after wherever its key came from: ~/.blobhub-worker/profiles/<name>/ for a stored
profile, ~/.blobhub-worker/keys/<digest>/ for a key supplied by flag or environment. Two credentials
therefore never share one. Run blobhub-worker whoami to see which tree a given invocation resolves to
— you need that path to author its config.yaml, and a key-derived one cannot be guessed.
Upgrading from a pre-profiles install migrates automatically on first login or start: the flat
~/.blobhub-worker/ files move into profiles/default/ and the credential moves into the shared store.
Run
blobhub-worker login # stores a profile; --api-key-stdin and --no-input make it scriptable
blobhub-worker start # run headless (structured JSON logs, for systemd/containers)
blobhub-worker start --tui # run with the live Textual dashboard
blobhub-worker whoami # which credential a start would use, and where its state lives
blobhub-worker profile ls # stored profiles, annotated with this machine's worker state
blobhub-worker instance ls # every worker state tree on this machine, and its state
blobhub-worker instance show <selector> # one instance in depth: identity, config, sections, threads
blobhub-worker instance stop <selector> # SIGTERM, wait, --force escalates to SIGKILL
A <selector> is an instance id (or a unique prefix of one), a profile name, key:<digest>, or a pid.
Global flags, matching blobhub: --json (machine-readable output, accepted at the root or on the
subcommand), -v/--verbose (extra diagnostic detail on stderr), -q/--quiet (suppress advisory
warnings), --version.
Configure the sections you want the worker to attach to in the state tree's config.yaml. See
Configuration for the config schema, and the
Specification for the per-section / per-thread state files written
alongside it.
The worker executes coding agents per thread metadata; see
Policies & approvals for the permission modes, and
Configuration for the agents config keys (executable, model,
effort, permissions).
How it works
- Attaches to BlobHub sessions, claiming a per-session
workerobject owned by your user. - Listens on the realtime API per section, sweeps the event stream every minute and on reconnect, and polls at the configured cadence while the realtime API is unreachable. For each thread it discovers, it drives a turn loop that coalesces user messages, runs one agent turn at a time, and posts the agent's emissions back as thread items.
- Supports interactive prompts: when the agent asks a question, the worker posts
a
pending_promptitem; the user replies with plain text and the worker resolves the answer to the agent. - Resumes cleanly after a worker restart (replays missed items, cancels stale prompts).
Documentation
The full guide and reference are at docs.blobhub.io.
License
MIT. See LICENSE.
Metadata
Release files for blobhub-worker 0.12.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| blobhub_worker-0.12.1.tar.gz | 219.2 kB | With provenance | Details for blobhub_worker-0.12.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| blobhub_worker-0.12.1-py3-none-any.whl | Python 3 | none | any | Details for blobhub_worker-0.12.1-py3-none-any.whl |
Total release size: 486.9 kB
Release files / blobhub_worker-0.12.1.tar.gz
| Download URL | blobhub_worker-0.12.1.tar.gz |
|---|---|
| Size | 219.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
89dbaeace86c533df89c1ee16a2dc82e464397fc759a0d5809873ff372dba483
|
|
BLAKE2b-256 checksum How to use checksums |
078a670f5083d1f58412c46a7437b1a63f88e27f272042c7549180c0c58bcd7f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / blobhub_worker-0.12.1-py3-none-any.whl
| Download URL | blobhub_worker-0.12.1-py3-none-any.whl |
|---|---|
| Size | 267.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ff72173bf23a2df47a310e693fdd90812852e522760ec05adf26e0b3bfcd811
|
|
BLAKE2b-256 checksum How to use checksums |
f015d66ab6ef51977221460b32e049e89a85ce8fef81d56739e8bd299f57e4af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for blobhub-worker 0.12.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for blobhub_worker-0.12.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.