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", "codex" or "agy" by agent type
    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

attachments:
  inbox: .blobhub/inbox          # default; the middle tier between a thread's own override and the codebase default

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 are claude_code, codex, and antigravity (Google’s Antigravity CLI, agy). (A test_double adapter exists for internal testing and is not user-visible.) None of the three agent CLIs ships with the worker — see Install for what each one needs on the host before a thread can be handed to it.

agents:
  claude_code:
    executable: claude
    model: claude-sonnet-4-6
    effort: high
    permissions: approval
  codex:
    executable: codex
  antigravity:
    executable: agy
    effort: medium

Key	Type	Default	Description
`executable`	string	`claude` (`claude_code`); `codex` (`codex`); `agy` (`antigravity`)	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. On `antigravity` this is mutually exclusive with `model`: most published Antigravity model slugs carry their own effort suffix and `agy` exits non-zero if given both, so the worker sends whichever is set and `model` wins when both are.
`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/agy 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 three supported harnesses do not see the same calls, so the same rule does different work on each. claude_code and antigravity route every tool call to the gate, which is also the only gate they have; codex runs inside an OS sandbox and asks only when a call escalates beyond it, so a rule written against write + outside: work_folder matches something different there. A policy is a guardrail against mistakes, not a sandbox, on any of the three. 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.

`attachments`

The worker’s own default inbox location — the middle tier of a three-tier, whole-value resolution: a thread’s own attachments.inbox (set on the thread session object) overrides this block’s inbox, which in turn overrides the codebase default. This block is optional; omitting it is equivalent to inbox: .blobhub/inbox — today’s behavior for every existing deployment.

attachments:
  inbox: .blobhub/inbox

Key	Type	Default	Description
`inbox`	string	`.blobhub/inbox`	`work_folder`-relative folder the worker materializes a thread’s incoming `file` attachments into, when no thread overrides it.

Unlike policy, there’s no on/off switch behind this: every tier resolves to some directory, and the worker always creates and uses one. For the full resolution order, the containment rule, and what happens when the resolved path escapes work_folder, see Job Session Object → Attachments.

`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

`attachments`

`sections`

`session_agent_harness` sections

`session`

Full working example

Validation

See also

​Top-level shape

​polling

​concurrency

​agents

​policy

​Rule shape

​attachments

​sections

​session_agent_harness sections

​session

​Full working example

​Validation

​See also

Top-level shape

`polling`

`concurrency`

`agents`

`policy`

Rule shape

`attachments`

`sections`

`session_agent_harness` sections

`session`

Full working example

Validation

See also