Filesystem Layout

The worker keeps all of its state under ~/.blobhub-worker/ (mode 0700). YAML is used for every file the user might want to read or edit. This page covers the generic top-level files. Per-section runtime state lives under jobs/ in subdirectories owned by each section’s job_type, documented on the job type’s filesystem page.

Top-level tree

~/.blobhub-worker/
├── identity.yaml                       # durable: user_id pulled from BlobHub at login
├── instance.yaml                       # per-process lock (pid + instance_id); auto-removed on clean shutdown
├── credentials.yaml                    # api.key + api.url; mode 0600
├── config.yaml                         # sections list; user-editable
├── logs/
│   └── {instance_id}/
│       └── worker.jsonl                # structured JSON-line log; written only in --tui mode
└── jobs/                               # per-section subtrees, owned by each section's job_type

File-by-file

`identity.yaml` — durable identity

Written by login. Records the user the worker acts as.

user:
  user_id: usr_01J...
  name: Egor Pushkin
  email: egor@example.com
  recorded_at: 2026-05-27T12:34:56Z

`instance.yaml` — single-instance lock

Atomically created at start with O_EXCL and removed on clean shutdown.

instance:
  instance_id: ins_01J...
  pid: 12345
  host: laptop.local
  version: 0.1.0
  started_at: 2026-05-27T12:35:00Z

A stale file with a dead PID is replaced on next start. A file with a live PID exits with WORKER_ALREADY_RUNNING.

`credentials.yaml` — API key

Written by login, mode 0600. The worker refuses to start if the file is world-readable (INSECURE_CREDENTIALS_PERMISSIONS).

api:
  key: bhk_...
  url: https://api.blobhub.io/v1

`config.yaml` — sections

User-edited. Full reference — generic blocks plus the per-section session block and per-agent settings — is on the Configuration page. The shape of each section depends on its job_type.

`logs/{instance_id}/worker.jsonl`

Structured log, one JSON record per line. Captures preflight, section dispatch (attach / refuse), transient API errors, and shutdown. Per-section detail goes to a section-scoped log under that section’s jobs/ subtree. This file is written only when the worker runs with --tui — the TUI redirects the log stream to keep the terminal clean. In headless mode the same records go to stderr instead and no file is written. Log rotation is not implemented; the file grows for the life of the instance.

The `jobs/` subtree

Each running section gets a directory under ~/.blobhub-worker/jobs/. The naming convention and the contents are owned by the section’s job_type. Today the only job type is session_agent_harness, which lays out:

jobs/
└── session_agent_harness-{session_id}/
    └── ...

Full reference: Session Agent Harness → Filesystem layout.

​Top-level tree

​File-by-file

​identity.yaml — durable identity

​instance.yaml — single-instance lock

​credentials.yaml — API key

​config.yaml — sections

​logs/{instance_id}/worker.jsonl

​The jobs/ subtree

​See also