Skip to main content

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 worker object 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_prompt item; 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)

Source distribution for blobhub-worker 0.12.1
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)

Table of built distributions (wheels) for blobhub-worker 0.12.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page