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 reads its declarative configuration from ~/.blobhub-worker/config.yaml. This page is the
complete reference for that file: the polling, concurrency, and agents blocks that tune the
worker globally, and the sections list that declares the work it runs. Edits take effect on the
next blobhub-worker start — there is no hot reload in v1.
The BlobHub API base URL lives in ~/.blobhub-worker/credentials.yaml (written by
blobhub-worker login) and is not configurable from config.yaml. To point
the worker at a different endpoint (staging, on-prem), re-run login and supply the new URL when
prompted, or hand-edit credentials.yaml’s api.url.
Top-level shape
polling:
interval_idle_ms: 1500
interval_active_ms: 3000
backoff_max_ms: 30000
concurrency:
max_agents: 4
agents:
claude_code:
executable: claude # default: "claude" for claude_code, "codex" for codex
model: claude-sonnet-4-6 # harness-specific string; default unset
effort: high # low|medium|high (portable) or a passthrough value; default unset
permissions: approval # autonomous|approval; default approval
sections:
- name: backend-feature # optional label
job_type: session_agent_harness
session:
org_id: org_01J...
blob_id: blb_01J...
revision_id: rev_01J...
session_id: ses_01J...
sections. Defaults are shown above.
polling
Adaptive cadence for any per-section poll loop that needs one.
| Key | Type | Default | Description |
|---|
interval_idle_ms | int | 1500 | Sleep between polls when the section is idle. |
interval_active_ms | int | 3000 | Sleep between polls while the section is doing work. |
backoff_max_ms | int | 30000 | Upper bound on exponential backoff after API errors. |
concurrency
| Key | Type | Default | Description |
|---|
max_agents | int | 4 | Maximum number of agent processes the worker runs simultaneously across all sections. Job types that don’t spawn agents ignore this. |
agents
A map of agent_type → per-agent settings. Job types that spawn coding agents (currently
session_agent_harness) read this block to decide how to
launch the agent inside each thread’s work_folder. Supported agent_type values for v1 are
claude_code and codex. (A test_double adapter exists for internal testing and is not
user-visible.)
agents:
claude_code:
executable: claude
model: claude-sonnet-4-6
effort: high
permissions: approval
codex:
executable: codex
| Key | Type | Default | Description |
|---|
executable | string | claude (for claude_code); codex (for codex) | Command name to resolve on PATH. |
model | string | unset | Harness-specific model identifier passed to the agent. Leave unset to use the agent’s own default. |
effort | string | unset | Reasoning effort. Portable values low, medium, high, or any harness-specific passthrough string. Unset = agent default. |
permissions | string | approval | autonomous runs without an approval gate; approval routes sensitive actions to the interactive prompt bridge (a human replies from the web UI), and denies them if no human is reachable. |
agent.* block (set on the thread session object) overrides the matching agents.<type> key here,
which in turn overrides the codebase default. Only permissions has a non-empty codebase default
(approval); executable falls back to claude/codex by agent type. For the full precedence
rules and the per-thread overrides, see
Job Session Object.
sections
A list. Each entry is a unit of work the worker runs. Every section has these generic fields:
| Key | Type | Required | Description |
|---|
name | string | No | Human-readable label shown in the dashboard. The default depends on the job type. |
job_type | string | Yes | The job type that handles this section. Must be one of the supported values. |
job_type. v1 ships one job type,
session_agent_harness, documented below.
session_agent_harness sections
A session_agent_harness section attaches the worker to one BlobHub session and drives a coding
agent for each thread session object handed off inside it.
- name: my-project # optional; defaults to session_id[:8]
job_type: session_agent_harness
session:
org_id: org_01J...
blob_id: blb_01J...
revision_id: rev_01J...
session_id: ses_01J...
| Key | Type | Required | Description |
|---|
name | string | No | Human-readable label shown in the dashboard. Defaults to session_id[:8] when omitted. |
job_type | string | Yes | Must be session_agent_harness. |
session | object | Yes | The four ids identifying the BlobHub session: org_id, blob_id, revision_id, session_id. All required. |
Full working example
A complete ~/.blobhub-worker/config.yaml with the global blocks set and one
session_agent_harness section fully populated.
polling:
interval_idle_ms: 1500
interval_active_ms: 3000
backoff_max_ms: 30000
concurrency:
max_agents: 2
agents:
claude_code:
executable: claude
model: claude-sonnet-4-6
effort: high
permissions: approval
sections:
- name: backend-feature
job_type: session_agent_harness
session:
org_id: org_01J3X4M5N6P7Q8R9S0T1U2V3W4
blob_id: blb_01J4P5Q6R7S8T9U0V1W2X3Y4Z5
revision_id: rev_01J7K8L9M0N1P2Q3R4S5T6U7V8
session_id: ses_01J9R0S1T2U3V4W5X6Y7Z8A9B0
~/.blobhub-worker/config.yaml, then run:
blobhub-worker login # one-time
blobhub-worker start --tui
instance.state = "pending" to hand it off to the worker — see
Handoff.
Validation
The configuration is validated on every start, before any section is dispatched.
| Error | Cause |
|---|
INVALID_CONFIG | The file is missing, unreadable, or not valid YAML. |
UNKNOWN_JOB_TYPE | A section’s job_type is not one of the supported values. |
MISSING_SESSION_KEYS | A session_agent_harness section’s session block is missing one of the four ids. |
DUPLICATE_SECTION_TARGET | Two sections target the same (org_id, blob_id, revision_id, session_id) tuple. |
INVALID_CONFIG, UNKNOWN_JOB_TYPE, MISSING_SESSION_KEYS,
DUPLICATE_SECTION_TARGET) and their remediation are catalogued on
Reference. Section- and thread-level codes for session_agent_harness are on
the Session Agent Harness reference.
See also
