Configuration

Configuration file reference

Configuration file reference #

pizza.yml (the default lookup path, override with -c/--config <file>) is read once at startup. Unknown keys are rejected — the node refuses to start on a typo, and on a key that was renamed in an upgrade. Individual keys can be overridden per launch with pizza -E <key>=<value> (repeatable; values parse as YAML, e.g. -E node.network.binding=127.0.0.1:12200).

Secret values #

API keys and tokens do not have to live in the file. Any string value may reference an environment variable, resolved at startup:

...

Environment variables

/ Configuration, / Environment

Environment variables #

Most tuning lives in pizza.yml (see the configuration file reference) or the runtime settings APIs. The PIZZA_* environment variables below are escape hatches — mostly for benchmarking, diagnostics and crash-safety research; prefer the config file or the settings APIs for anything you want to keep.

Operational knobs #

Variable	Default	Description
`PIZZA_FLUSH_CONCURRENCY`	unset	Overrides `node.flush_concurrency` (1..=16); beats the config file.
`PIZZA_RECOVERY_TAIL_FLUSH`	unset	`0`/`1` forces `wal.local.recovery_tail_flush` off/on, beating the config file.
`PIZZA_RPC_TIMEOUT_SECS`	unset	Deadline for cluster RPC calls (must be > 0).
`PIZZA_COMPACTION_EVERY_TICKS`	unset	Maintenance ticks (500 ms) between background compaction passes.
`PIZZA_COMPACT_TIERS`	unset	Restrict background compaction to specific tier patterns (diagnostics).
`PIZZA_FLUSH_AFTER_IDLE_TICKS`	unset	Idle-tail epoch flush override (same semantics as `wal.local.epoch_flush_after_idle_ticks`).
`PIZZA_SEGMENT_SYNC`	unset	`off` skips the per-segment fsync before WAL purge — the same behavior as `wal.local.segment_durability: async`, without a config change.
`PIZZA_WAL_IO_URING`	unset	Force WAL io_uring on/off (Linux), overriding auto-detection.
`PIZZA_MAX_NODE_BUILDS`	unset	Fallback for the epoch-build concurrency default (`PUT /_node/_local/settings/epoch_build` overrides it at runtime).
`PIZZA_MERGE_POOL_THREADS`	unset	Size of the dedicated compaction merge thread pool.
`PIZZA_ROUTE_CACHE`	unset	Routing-table cache diagnostics/tuning.
`PIZZA_BUILD_BUF_POOL_MB`	unset	Build-buffer pool size in MiB.

Watchdog #

Variable	Default	Description
`PIZZA_RSS_WATCHDOG`	unset	Enable the RSS watchdog (`0` explicitly disables it).
`PIZZA_RSS_SOFT_MB`	60% of MemTotal	Soft RSS threshold (MiB) — sheds load, logs.
`PIZZA_RSS_HARD_MB`	75% of MemTotal	Hard RSS threshold (MiB) — aborts the process.

Diagnostics and profiling #

Off by default; presence enables.

...

AI Services

/ Embedding, / Configuration, / Ai, / Chat

AI services are the external, OpenAI-compatible model endpoints behind server-side inference — schema-driven text→vector derivation, text vector queries, the semantic query and the /_embedding API on the embedding side, and the POST /_chat generation facade on the other. Every service speaks the OpenAI wire format: the embeddings API (POST {url} with {"model", "input": [...]} and a bearer key), and — once it lists generation models — the chat-completions API at its chat_url.

...

Keystore

/ Keystore, / Security, / Configuration

Keystore #

The keystore is a node-local file of secrets referenced from pizza.yml — API keys and tokens never have to live in the config file itself. Entries resolve through ${keystore:NAME} references:

node:
  embedding:
    endpoints:
      - name: openai
        url: https://api.openai.com/v1/embeddings
        api_key: ${keystore:openai}

The file is <config dir>/keystore.json — next to the config file it serves, so one instance per config (multi-instance hosts keep separate keystores) and it never enters the data directory’s lifecycle. It is written 0600 and replaced atomically; entries never enter cluster metadata, raft logs, or API responses — views answer with a masked hint only (sk-…4f2a).

...

Keystore hot-reload

/ Keystore, / Security, / Configuration

Keystore hot-reload #

Rotating a secret no longer restarts the node. ${keystore:...} references re-resolve into the running configuration on demand: console edits trigger the reload themselves, and out-of-band changes (a CLI edit, a replaced mounted Secret) are one call away.

curl -X POST http://127.0.0.1:28000/_node/_local/keystore/_reload \
  -H 'Authorization: Bearer pz_bootstrap_key'

The answer says exactly what happened — key names only, values stay write-only:

{
  "entries": 3,
  "read_only": false,
  "references": 2,
  "changed": ["node.embedding.endpoints", "catalog.join_token"],
  "unchanged": 0,
  "failed": []
}

A rotated embedding API key applies to the next inference call; a rotated catalog.join_token to the next join attempt. A reference whose entry disappeared keeps its running value and lands in failed until the entry returns — reload never aborts the node the way a missing entry aborts boot.

...