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.
• Polls session events; for each thread it discovers, 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.