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

# Filesystem Layout

> What the worker reads and writes under ~/.blobhub-worker/

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`](/worker/job-types), 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`](/worker/cli/login). Records the user the worker acts as.

```yaml theme={null}
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.

```yaml theme={null}
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`).

```yaml theme={null}
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](/worker/configuration) page. The shape of each section depends on
its [`job_type`](/worker/job-types).

### `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](/worker/session-agent-harness/filesystem).

## See also

* [Configuration](/worker/configuration)
* [Job types](/worker/job-types)
* [Session Agent Harness → Filesystem layout](/worker/session-agent-harness/filesystem)