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 in ~/.blobhub/credentials.yaml
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

Profiles

A profile is a named API key plus the API URL it belongs to, 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 and --api-url / BLOBHUB_API_URL outrank it, exactly as in the CLI.

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.