Reference

Reader and writer settings

Two crews, two sets of limits.

In short

  • [reader] bounds concurrency, the local mirror, version checks and response size; [reader.http] turns on Streamable HTTP MCP.
  • [writer] sets retention windows, document and envelope limits, commit groups, maintenance, backpressure and writer serve.
  • Keys have defaults or may stay absent, except listen and public_url in [reader.http] and listen and operator_token in [writer.serve.admin].

Durations and byte sizes are written as described under secrets. The [reader] keys for search depth and memory are under advanced tuning.

[reader]

KeyDefaultMeaning
concurrency81–16 requests executing at once; the waiting queue has the same bound, then busy.
filter_count_max_rows10000001–10,000,000 authorized rows one list_filters call may inspect; over it, busy.
mirror_pathabsent ($XDG_CACHE_HOME/fyrr/<namespace>, else ~/.cache/fyrr/<namespace>)Private local directory of immutable read-through files (mode 0700, files 0600, owned by the process, not a symlink), created on first use. The default does not depend on the working directory; a relative mirror_path resolves against it. Without the setting and without an absolute XDG_CACHE_HOME or HOME, the reader refuses to start (storage_configuration_invalid).
mirror_max_bytes8589934592Disk limit of the mirror in bytes (8 GiB). An integer; unit suffixes are refused.
version_checkintervalinterval, off or per-request.
version_check_interval30sBackground scheduler caps the effective interval at 30 s.
per_request_wait2sper-request mode: wait this long for a newer version, then serve the old one flagged stale_version.
max_preparation15mUpper bound on preparing a new generation.
max_response_bytesabsent4096–16777216: budget for a serialized search result. Over it, whole hits are dropped from the end of the rank order (each query keeps at least four), then the lowest-ranked hits lose their excerpt or content; truncated and omitted_bytes report what was removed.
httpabsentStreamable HTTP MCP, see below.

The fixed default of eight supports eight simultaneous clients even on two-core hosts, where embedding and storage waits can overlap. Set concurrency explicitly (1–16) for your workload. Each request uses an independent prepared reader; shared native caches are not multiplied by concurrency. Its accounted private row-state cost is 64 bytes per physical Lance row per prepared reader: 20,000 rows cost 1,280,000 bytes (1.22 MiB). Documents can span many rows. The scheduler prepares concurrency workers, or twice that when embedding.reader_live = true, plus one template. At eight and 20,000 rows, that is 10.99 MiB (20.75 MiB with live embeddings), plus the shared 32 MiB base reservation. These are derived preparation allowances, not measured total RSS or a ceiling on per-request scan and response allocations. See memory sizing before raising concurrency. On the preserved 20,000-document index (20,020 physical rows), a measurement with fresh processes found about 0.33 MiB of additional idle RSS per prepared reader; the conservative row-state allowance is 1.22 MiB. Active requests and handover require additional space. See the measurement and 1M-row example in memory sizing. Pin concurrency = 2 to retain the previous request and queue limits.

[reader.http]

KeyDefaultMeaning
listenrequiredIP socket address (IP:port). The listener speaks plain HTTP; see HTTP boundary.
public_urlrequired1–2048 characters: the https://…/mcp URL clients use (the path must be /mcp; plain HTTP only on loopback); the Host header must match its authority on every route except /readyz.
operator_credentialabsent{ env = "VAR" } for POST /admin/refresh; separate from OIDC access tokens. Absent, the route is not served (404); readers still pick up new versions through version_check.
authorization_cache_subjects641–1024 subjects whose admission is cached (LRU, 128 MiB accounted bound).
user_requests_per_minute120At least 1, per canonical user; linked subjects share it.
group_requests_per_minute120At least 1, per published group membership.

[writer]

KeyDefaultMeaning
purge_window1dDeleted or revoked content leaves old versions and mirrors within it. Must exceed version_grace.
version_grace1hMinimum retention of a version after it stopped serving. Must exceed 300 s plus reader.max_preparation.
max_envelope_age3dOlder pending envelopes are rejected, forcing a re-scan. At most 6 days: Lance keeps unreferenced files for 7 days.
document_max_bytes8MiBLarger documents are quarantined.
envelope_max_rows50000At least 1. Provider content batches are further capped by writer.commit.group_max_rows and 256.
envelope_max_bytes256MiBMust exceed every document size limit.
worker_memory_max_bytes2GiBCommitted-memory ceiling of one provider worker (RLIMIT_DATA).
credentials{}Maps a provider's environment reference to a stored credential name (fyrr writer credential).

[writer.commit]

KeyDefaultMeaning
group_max_rows1000000At least 1 row per publication group.
group_max_bytes4GiBBytes per publication group; a group must hold a full envelope.
coalescing_timer1mwriter serve closes a group after this long.
lease_ttl1mNamespace lease duration.
merge_fts_segmentsfalseMerge lexical deltas before publication.

[writer.maintenance], [writer.backpressure], [writer.serve]

KeyDefaultMeaning
maintenance.step_max_duration5mTime budget of one lease-held maintenance step.
backpressure.max_pending_content_envelopes1000At least 1. Content sync pauses above it; permissions and members still publish.
backpressure.max_pending_content_bytes16GiB
serve.committertrueRun the committer role in writer serve; off keeps polling and leaves publication to batch commit jobs.
serve.adminabsentWriter administration listener: listen, operator_token = { env = "VAR" }, tls_terminated (required for a non-loopback listener). Needs identity.encryption_key.

Edit this page on GitHub ↗