Concepts

Documentation Index

Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt

Use this file to discover all available pages before exploring further.

The worker is a long-running process that connects coding agents on your own infrastructure to BlobHub sessions. This page covers the handful of concepts you need before connecting it to your sessions: how the worker acts as a user, how it is organized into sections by job type, how it drives an agent per thread, and the control channel a user uses to hand work to the worker and get it back.

​

Worker process & identity

A single worker is one long-running process that authenticates to BlobHub as one BlobHub user — the identity recorded by blobhub-worker login. Every API call the worker makes (reading sessions, posting thread items, updating envelopes) is made as that user, with that user’s access. Because the worker filters its own emissions out of the inbound stream using only user_id, posts made by the same user the worker runs as are treated as the worker’s own and are not forwarded to the agent. Run the worker under a dedicated service-account user with its own API key so that humans posting into a thread as themselves are seen as not-self and reach the agent.

​

Sections & job types

The unit of organization is a section: one entry under sections in config.yaml describing a single unit of work the worker should run. Each section names a job_type, the discriminator that selects what the section attaches to and how it behaves at runtime. session_agent_harness is the only job type in v1. See Job Types for the discriminator and how new job types are added.

​

Sessions, threads & the agent

A session_agent_harness section attaches to one BlobHub session. Inside that session it discovers thread-typed session objects and treats each one as a unit of work — a “job”. For each thread it hands off, the worker drives one coding agent (Claude Code or Codex) in that thread’s work_folder on the worker host, streaming the agent’s output back as thread items and feeding inbound posts to the agent. One agent runs per active thread. The session is shared; the worker marks its attachment with a single worker session object that doubles as an activity log.

​

The control channel

A user hands a thread to the worker, and takes it back, through one field on the thread session object’s envelope: instance.state. The user sets pending to hand off, sets completed to stop the worker cleanly, and resets failed → pending to retry. The worker writes only active and failed. It never writes completed. See Handoff for the full state machine.

​

Agents, models, effort, permissions

A thread can specify which agent runs and how. The user-facing knobs are the agent type (claude_code or codex), an optional executable, model, effort (low | medium | high, or a harness-specific passthrough string), and permissions. permissions controls the approval gate:

• autonomous — the agent acts without an approval gate.
• approval (default) — sensitive actions are routed to an interactive prompt that a human answers from the web UI. If no human is reachable, the action is denied.

These knobs resolve through three tiers — the thread’s own agent.* settings, then the worker’s agents.<type> config, then the codebase default — with the most specific winning per field. See Configuration for where you set them.

​

Concurrency & run modes

concurrency.max_agents in config.yaml caps how many agents run at once across all sections. A thread that goes pending while the worker is at capacity waits for a slot to free before activating. The worker runs in two modes:

• Headless (default) — structured JSON log lines go to stderr; suitable for systemd, a container supervisor, or tmux.
• --tui — a live Textual dashboard; logs are redirected to a file instead of stderr.

See blobhub-worker start for both modes.

​

See also

• blobhub-worker start
• Configuration
• Introduction
• Session Agent Harness