Configuration reference

YoloSearch has one configuration catalog. Every setting in it has a dotted key, a kind, a scope, a default, an environment variable, and — unless it is a secret or a compile-time value — a flag. The same key means the same thing in a file, in the environment, on a command line, and through the runtime API.

The configuration guide explains the model. This page is the table.

Later layers win:

default  <  file  <  environment  <  flag  <  runtime API (config set)

Every value carries its provenance. config get, config list, and config export show it.

Scope says what may change at runtime.

Only node-runtime settings accept config set. A startup setting can still be put in a file or the environment; it just needs a restart to take effect.

The three spellings of a setting derive from its key mechanically:

The environment name is YOLOSEARCH_ followed by the key with every . and _ rendered as _. Some settings carry a short alias as well as the derived long flag; both work, and the tables below name the alias where one exists.

Files are discovered in a fixed order, and later files override earlier ones:

1. /etc/yolosearch/yolosearch.yml, then /etc/yolosearch/conf.d/*.yml
2. $XDG_CONFIG_HOME/yolosearch/yolosearch.yml (default ~/.config/yolosearch/), then its conf.d/*.yml
3. ./yolosearch.yml
4. <data-dir>/config.yaml, when --data-dir is set
5. --config-dir DIR's *.yml, in name order
6. --config FILE

.yaml is accepted wherever .yml is. --config-search=false (YOLOSEARCH_CONFIG_SEARCH=false) skips the default locations entirely.

A file nests keys under their sections:

server:
  listen: 0.0.0.0:9500
object:
  backend: s3
  s3:
    endpoint: minio:9000
    bucket: yolosearch
    path_style: true
cache:
  full_bytes: 8GiB
storage:
  mode: AUTO

Four settings are read from the environment only. They have no flag, never appear in a file, and are never copied into a rendered command line or a Kubernetes custom-resource status.

Leaving every S3 credential setting empty lets the ambient credential chain resolve and refresh one. Supplying an expiring access and secret pair without object.s3.session_token is rejected by the provider.

Two settings exist only to derive others, and both apply their derivation only where nothing more specific was set.

The listener, identity, roles, and the request size limits.

The authoritative store. The three S3 credential settings are read from the environment only — never a flag, never a file.

Which index a catalog-bound role serves, and which generation it pins.

Where configuration files come from and whether they are watched.

Used by the client verbs; ignored by a server process.

Four tiers: two on local disk, two in process memory. All of them are startup settings except the scrubber.

What AUTO weighs when it chooses between hydration and remote blocks.

Who a role talks to. Every one of these is a startup setting.

Admission limits on the router and the seal triggers on the builder.

One build's accounted budget and the derivations that hang off it.

Lease-fenced catalog publication.

How a node tracks the catalog and how long it keeps retired engines.

Size-tiered physical merging of active segments.

Two-phase object reclamation. Both phases are off by default.

Server-side ceilings on what a request may ask for.

The bounded approximate lexical tail. Off by default.

IVF-PQ construction and per-request candidate generation.

The four embedding providers, their limits, and the model cache.

Compile-time and display-only.

config.watch defaults to true: the discovered configuration files are reloaded when any of them changes. A reload that is refused leaves the previous configuration in place, and that refusal is visible in metrics before it is visible in logs:

• Configuration guide — the model, with worked examples
• Sizing — how these settings affect capacity
• CLI reference — the commands that read and change them