Configuration - BlobHub

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

Every top-level block is optional except 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.

These settings are the middle tier of a three-tier, per-field resolution: a thread’s own 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.

Everything else under a section is determined by its 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

Save this file at ~/.blobhub-worker/config.yaml, then run:

blobhub-worker login           # one-time
blobhub-worker start --tui

Once running, prepare a thread session object inside that session and set 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.

Process-level codes (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.

​Top-level shape

​polling

​concurrency

​agents

​sections

​session_agent_harness sections

​Full working example

​Validation

​See also