Configuration

The worker reads its declarative configuration from config.yaml inside the profile’s own state tree — ~/.blobhub-worker/profiles/{profile}/config.yaml, so each profile watches its own sessions. blobhub-worker whoami prints the tree a given invocation resolves to; for what is running on this machine and what it is doing, see instance ls/show instead. 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 belongs to the profile, not to config.yaml. It is stored alongside the key in ~/.blobhub/credentials.yaml (written by blobhub-worker login) and can be overridden per run with --api-url or BLOBHUB_API_URL. To point a worker at a different endpoint, log in under a second profile name and run start --profile <name> — that gives the other endpoint its own configuration and cursors rather than reusing this one’s.

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|guarded; default approval

policy:
  allow_autonomous: true         # default; the operator's ceiling on `permissions: autonomous`
  rules: []                      # evaluated BEFORE any thread policy; see "policy" below

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...        # a uuid, OR a session alias (resolved once at attach)
      session_prefix: ""            # optional; "" (default) = the whole session

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 every sensitive action to the interactive prompt bridge (a human replies from the web UI), denying it if no human is reachable; `guarded` routes sensitive actions to a rule set first (see `policy` below), falling back to that same human prompt only when a rule — or the absence of one — says `ask`.

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.

`policy`

The operator’s rule set and ceiling for any thread running with permissions: guarded (see the agents table above). This block is optional; omitting it is equivalent to allow_autonomous: true with no rules — today’s behavior for every existing deployment.

policy:
  allow_autonomous: true          # default; false forbids `permissions: autonomous` worker-wide
  rules:                          # evaluated BEFORE any thread policy, in order
    - id: confine_writes
      effect: write
      outside: work_folder
      action: deny
    - id: never_force_push
      effect: exec
      command: ["git push --force*", "git push -f*"]
      action: deny

Key	Type	Default	Description
`allow_autonomous`	bool	`true`	Ceiling on `permissions: autonomous`. When `false`, a thread requesting `autonomous` fails activation with `POLICY_AUTONOMOUS_FORBIDDEN` instead of silently running under a weaker mode.
`rules`	list	`[]`	Rules evaluated against every intercepted tool call on a `guarded` thread, before that thread’s own `policy.rules` (set on the thread session object; see Job Session Object). A machine owner’s `deny` here can never be relaxed by anything a session supplies.

Rule shape

Each entry in rules — both here and in a thread’s own policy block — has the same shape:

Field	Type	Meaning
`id`	string	Identifies the rule in `policy_applied` / `policy_denied` audit items and in activation warnings.
`effect`	string	`write` \| `exec` \| `read` \| `network` — the portable action a rule matches. See the per-harness mapping below.
`outside`	string	`work_folder` matches a call whose resolved path leaves the run’s workspace. Leave unset to match regardless of path.
`command`	list	Glob patterns (`fnmatchcase` — case-sensitive) matched against the command line. `exec` only; ignored for other effects.
`action`	string	`allow` \| `deny` \| `ask`. `ask` routes to the same human prompt bridge `permissions: approval` uses; with no human reachable, it denies.

Rules are evaluated first match wins, in this order: this section’s rules, then the thread’s own policy.rules, falling through to the thread policy’s default (allow | ask | deny) when nothing matches. The worker config carries rules only — default belongs to the thread’s own policy, because a machine-wide default would be a ceiling on nothing in particular. effect is a portable vocabulary, but the two supported harnesses do not see the same calls — a rule written against write + outside: work_folder behaves differently on claude_code than on codex, and a policy is a guardrail against mistakes, not a sandbox. Before writing rules for a sensitive workspace, read Job Session Object → Policy and guarded permissions for the full evaluation model, the per-harness capability table, and what a policy cannot enforce.

`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...             # a uuid, OR a session alias
    session_prefix: "projects/"        # optional; "" (default) = the whole session

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	Identifies the BlobHub session and, optionally, the slice of its namespace to watch. See below.

`session`

Key	Type	Required	Description
`org_id`	string	Yes	Organization id.
`blob_id`	string	Yes	Blob id.
`revision_id`	string	Yes	Revision id.
`session_id`	string	Yes	A session uuid, or a session alias — the worker resolves either, once, at attach (via `get_session`), and uses the resolved id for every call after that. An alias buys a stable, readable name in `config.yaml` and a session that can be re-created without editing config. A value that resolves to neither a live id nor a live alias refuses the section with `SESSION_NOT_FOUND`.
`session_prefix`	string	No	Scopes this section to one slice of the session’s object namespace, e.g. `"projects/"`. Defaults to `""` — the whole session, today’s behavior for every existing deployment. When set, it must end in `/` and may not contain a `.` or `..` segment; it is matched as a plain string prefix against each object’s alias. See Concepts for what scoping a section this way actually changes about discovery.

job_id — the on-disk state directory under the profile’s own jobs/ — is always derived from the resolved session id, never from the configured spelling: a session re-created under the same alias is a different session, and its threads must not inherit the old session’s local state. See Filesystem Layout. Two sections may not name the exact same (org_id, blob_id, revision_id, session_id, session_prefix) tuple (DUPLICATE_SECTION_TARGET at load; see Validation below) — but because session_id can be spelled as either an id or an alias, one section naming a session by id and another naming the same session by alias will not be caught by that static check. The worker repeats the check after resolution: whichever section’s reference resolves second refuses to attach with the same DUPLICATE_SECTION_TARGET code, while the worker keeps serving every other section. See Session Agent Harness → Reference for that section-level form.

Full working example

A complete config.yaml with the global blocks set, a policy ceiling, and one session_agent_harness section watching a slice of a session named by alias.

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: guarded

policy:
  allow_autonomous: true
  rules:
    - id: confine_writes
      effect: write
      outside: work_folder
      action: deny
    - id: never_force_push
      effect: exec
      command: ["git push --force*", "git push -f*"]
      action: deny

sections:
  - name: backend-feature
    job_type: session_agent_harness
    session:
      org_id: org_01J3X4M5N6P7Q8R9S0T1U2V3W4
      blob_id: blb_01J4P5Q6R7S8T9U0V1W2X3Y4Z5
      revision_id: rev_01J7K8L9M0N1P2Q3R4S5T6U7V8
      session_id: work-prod                  # a session alias, resolved once at attach
      session_prefix: "projects/"            # only watch this slice of the session's namespace

A minimal single-section example — the same shape with a uuid session_id, no session_prefix, and permissions: approval — needs nothing beyond the Top-level shape block above. Save this file at ~/.blobhub-worker/profiles/default/config.yaml (or wherever blobhub-worker whoami reports), 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 — or a section’s `session_prefix`, or the top-level `policy` block, fails validation (see below).
`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, session_prefix)` tuple.

session_prefix, when set, must match ([A-Za-z0-9._@-]+/)+ — one or more path segments each ending in /, with no . or .. segment. The top-level policy.rules are checked against the same effect / action vocabulary documented under policy above; an unknown value fails with INVALID_CONFIG naming the offending rule. 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 — including POLICY_MISSING, POLICY_INVALID, POLICY_AUTONOMOUS_FORBIDDEN, and the section-level, post-resolution form of DUPLICATE_SECTION_TARGET — are on the Session Agent Harness reference.

Overview

Specification

Top-level shape

`polling`

`concurrency`

`agents`

`policy`

Rule shape

`sections`

`session_agent_harness` sections

`session`

Full working example

Validation

See also

​Top-level shape

​polling

​concurrency

​agents

​policy

​Rule shape

​sections

​session_agent_harness sections

​session

​Full working example

​Validation

​See also

Top-level shape

`polling`

`concurrency`

`agents`

`policy`

Rule shape

`sections`

`session_agent_harness` sections

`session`

Full working example

Validation

See also