Skip to main content

blobhub-worker

External worker process that runs coding agents (Claude Code, Codex) against BlobHub session threads. It connects to api.blobhub.io over HTTPS + WebSocket, attaches to one or more sessions, and drives the configured agent through each thread's conversation — posting agent emissions back as thread items in real time.

Install

pipx install blobhub-worker

Requires Python 3.12+.

Use

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.

Profiles

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.

Configure the sections you want the worker to attach to in that tree's config.yaml. See the documentation for the config schema and the per-section / per-thread state files written alongside it.

The worker executes coding agents per thread metadata; see AGENTS.md "Trust boundary" for the autonomous/approval security model and the agents config keys (executable, model, effort, permissions).

What it does

  • 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).

License

MIT. See LICENSE.

Metadata

Release files for blobhub-worker 0.12.0

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.0
File Size Uploaded Provenance Actions
blobhub_worker-0.12.0.tar.gz 218.6 kB With provenance Details for blobhub_worker-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for blobhub-worker 0.12.0
File Interpreter ABI Platform Actions
blobhub_worker-0.12.0-py3-none-any.whl Python 3 none any Details for blobhub_worker-0.12.0-py3-none-any.whl

Total release size: 485.8 kB

Release files / blobhub_worker-0.12.0.tar.gz

Download URL blobhub_worker-0.12.0.tar.gz
Size 218.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1c82d6e01be55154d49927373104e617a4845148abff5f7f1607a9ffc25d005e
BLAKE2b-256 checksum
How to use checksums
c1061ef7298257ebed6d5ca21ce71cde0208e961c7d210cdd06d0d2ba29aa4a1
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 13, 2026.

Transparency log

Release files / blobhub_worker-0.12.0-py3-none-any.whl

Download URL blobhub_worker-0.12.0-py3-none-any.whl
Size 267.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a43dd38aaab72b976a2ad75fbbe646ec0b51ff46afcd7d5faa7f8f5a8906431f
BLAKE2b-256 checksum
How to use checksums
403edb712ace5943066f25f9569ee563ee0ac4081db1cd301334c85b9260b751
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 13, 2026.

Transparency log

Security for blobhub-worker 0.12.0

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.0.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 13, 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