.env.example

# EdgeProc configuration — the complete surface.
#
# Copy to `.env` (git-ignored) and adjust. Every value is optional: the defaults shown
# here are the ones the library uses when the variable is unset. Variables are read
# under the `EDGEPROC_` prefix (except HF_TOKEN, which uses the ecosystem-standard name).
# Unrelated variables in a host application's own `.env` are ignored, not rejected.

# ---------------------------------------------------------------------------------
# Local vector runtime
# ---------------------------------------------------------------------------------

# Embedding model the local vector runtime / `edgeproc route` use to encode text. This is
# a HUB REFERENCE and is only used when a download is permitted (see the two vars below).
EDGEPROC_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2

# The offline path. A device that has synced a bundle still cannot answer a query unless
# the MODEL is local too — otherwise sentence-transformers resolves the name above by
# calling huggingface.co. Ship the model inside the signed bundle and point this at the
# directory `edgeproc sync --materialize-to` wrote.
# EDGEPROC_MODEL_PATH=./materialized/model

# sha256 pin over EDGEPROC_MODEL_PATH, for a model that did NOT arrive through `sync`
# (a synced bundle is already verified against the trust root). A mismatch is refused,
# not warned. Compute it with:
#   python -c "from pathlib import Path; from edgeproc.localvec.model_source import \
#     digest_model_dir; print(digest_model_dir(Path('./materialized/model')))"
# EDGEPROC_MODEL_DIGEST=

# Permit fetching the model from the hub. OFF by default and deliberately so: with no
# local model configured, EdgeProc REFUSES rather than quietly reaching the network at
# the first query. Turn this on for provisioning on a build machine, not on a device.
# EDGEPROC_ALLOW_MODEL_DOWNLOAD=1

# Default top-k when a SEARCH/RANK task omits payload.k.
EDGEPROC_DEFAULT_K=10

# Reciprocal-rank-fusion rank window. A bigger value flattens the score curve, so a
# top-ranked hit in one retriever wins by less when fusing vector + keyword results.
EDGEPROC_RRF_K_WINDOW=60

# Seconds to wait for the cross-process FAISS snapshot lock. Save, load, legacy
# migration, and generation GC share this boundary so none can race another process.
EDGEPROC_SNAPSHOT_LOCK_TIMEOUT=30.0

# Hugging Face token for authenticated / gated model downloads (ecosystem-standard name,
# no EDGEPROC_ prefix). Leave unset for public models.
# HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx

# ---------------------------------------------------------------------------------
# Trust root — required for `edgeproc sync`
# ---------------------------------------------------------------------------------

# Path to the pinned trust root: a raw ed25519 `public.key` (what `edgeproc keygen`
# writes) or a JSON keyring (`edgeproc keyring init`). `edgeproc sync` refuses to run
# without this (or an explicit --key) — an unverifiable sync is rejected, fail-closed.
# EDGEPROC_TRUST_ROOT_PUBKEY_PATH=keys/public.key

# ---------------------------------------------------------------------------------
# Publisher stamping — OFF by default; upgrade every consumer BEFORE turning it on
# ---------------------------------------------------------------------------------
# Sign the signing key's key_id into the pointer (`edgeproc publish --stamp-key-id`).
# EDGEPROC_PUBLISH_STAMP_KEY_ID=false
# Sign expires_at = now + this duration: seconds, or 90s / 30m / 12h / 7d / 2w
# (`edgeproc publish --expires-in`). Re-publish before it lapses.
# EDGEPROC_PUBLISH_EXPIRES_IN=7d

# ---------------------------------------------------------------------------------
# Bundle sync — network and fail-closed resource ceilings
# ---------------------------------------------------------------------------------
# These bound what a hostile or runaway origin can make one sync do. Lower them for
# small catalogs; the defaults are generous enough never to reject a legitimate bundle.

# HTTP timeout (seconds) per fetch of a pointer, manifest, or chunk.
EDGEPROC_HTTP_TIMEOUT=30.0

# Max bytes accepted from a SINGLE HTTP response body (bounds a hostile origin).
EDGEPROC_MAX_FETCH_BYTES=268435456

# Max plaintext bytes a single chunk may decompress to (zstd decompression-bomb defense).
# A real chunk is <= 256 KiB, so 64 MiB is headroom that still refuses a bomb.
EDGEPROC_MAX_DECOMPRESSED_BYTES=67108864

# Aggregate per-sync ceilings (disk-exhaustion defense): one sync refuses to pull past
# these totals no matter how many chunks or files the signed manifest enumerates.
EDGEPROC_MAX_SYNC_TOTAL_BYTES=4294967296
EDGEPROC_MAX_SYNC_FILES=100000

# Max bytes for one materialized file, keeping that explicit allocation bounded.
EDGEPROC_MAX_MATERIALIZE_BYTES=268435456

# Seconds to wait for the cross-process filesystem mutation lock before failing
# retryably. A wedged peer must not make sync / promote / gc block forever.
EDGEPROC_MUTATION_LOCK_TIMEOUT=30.0

# ---------------------------------------------------------------------------------
# Task budgets and admission control
# ---------------------------------------------------------------------------------

# Defaults stamped onto a Task when it declares no budget of its own.
EDGEPROC_TASK_BUDGET_MS=5000
EDGEPROC_TASK_BUDGET_MEMORY_MB=256

# Sum of declared task reservations one EdgeProc instance admits concurrently. This is
# deterministic admission control over DECLARED budgets — not a native-RSS hard limit.
# The host must still set its own process/container memory limit.
EDGEPROC_MAX_IN_FLIGHT_MEMORY_MB=512