Copy page View as Markdown

Configuration reference

This page lists every VAULTSPEC_RAG_* environment variable vaultspec-rag declares. It gives the matching command-line interface (CLI) flag where one exists, and the rules for parsing values.

Examples use the installed-tool form and call vaultspec-rag directly. If vaultspec-rag is a project dependency, prefix each command with uv run; see the installation guide for lane selection, including the standalone tool and no-install routes.

On this page

• Resolution order - which source wins when more than one sets a value

• Type coercion - how values are parsed, and what a rejected value does

• Variables with their own parsing rules - variables that resolve differently

• Core variables - every variable resolved through the standard chain, grouped by what it affects

• Config-only keys - settings with no environment variable

• Hugging Face cache - the third-party variables that govern model downloads

• Download sources - where the server binary, the models and the CUDA wheels come from

• Renamed and removed variables - old names and what replaced them

• Tuning for memory and speed - task guidance rather than reference

• Examples

Related guides: the installation guide for where to set variables before first run, the CLI reference for the full flag context, the storage backends guide for the server-first backend model, the architecture overview for the runtime concepts named here, the glossary for the vocabulary, and the preprocessing hooks guide for the .vaultragpreprocess.toml rule format.

Resolution order

Each setting resolves through a fixed precedence, highest first: invocation (a CLI flag), the session environment, a workspace .env (credentials only, see below), persisted configuration where a knob has one, then the built-in default. This is the one order every vaultspec package follows, not a rule specific to this page.

Three settings chain the session-environment rung to a shared framework name read behind this package’s own scoped name, so a session that exports only the shared name configures every vaultspec tool at once:

This package’s variable	Falls back to (framework-wide)
VAULTSPEC_RAG_ROOT	VAULTSPEC_TARGET_DIR
VAULTSPEC_RAG_LOG_LEVEL	VAULTSPEC_LOG_LEVEL
VAULTSPEC_RAG_STDIO_WATCHDOG	VAULTSPEC_STDIO_WATCHDOG

No other variable on this page reads a shared framework name; every other row resolves against its own scoped name alone.

A workspace-root .env is read for only VAULTSPEC_RAG_TYPESAFE_API_KEY - and only when both hold: the running interpreter lives inside that workspace, and this package’s resolved install mode there is dependency or dev, never a globally installed tool. No other variable on this page is ever read from a .env, and no variant (.env.local and the like) is read at all. This is a settings file, not a repository surface: repository content may hand you a credential, never reconfigure the tool.

The persisted local-only marker applies only to backend selection. It lives at {status_dir}/local-only.json and is written by install --local-only - server start --local-only applies to that run without persisting. A later server start with no flag and no environment variable then still selects the on-disk store.

Some variables sit outside the CLI/environment/default chain and resolve their values their own way. See Variables with their own parsing rules.

Type coercion

The loader parses and validates every value as it builds the settings. It reports a rejected value once, at startup, not when something first reads that setting. One unusable value anywhere makes the whole settings object unbuildable.

• Booleans: 1, true, yes and on parse as true; 0, false, no and off parse as false (case-insensitive). These spellings are the same for every boolean vaultspec-rag reads, including the ones in Variables with their own parsing rules - no variable reads off as on. Any other value is rejected with a message naming the variable and listing the accepted spellings, so a typo such as treu is refused instead of silently reading as false and turning the feature off.

• Integers and floats: parsed with int() and float(); a non-numeric value is rejected the same way.

• Paths: relative paths resolve against the project root; absolute paths are used as given. Use forward slashes on Windows.

• Empty values: an empty or whitespace-only value is treated as unset and falls back to the next rung, for every setting on this page regardless of type - a boolean included. This keeps an unexpanded VAR="$UNSET" from repointing a managed directory at the working directory, or from silently turning a switch off. VAULTSPEC_RAG_STDIO_WATCHDOG is the single exception: a blank value there leaves the protective switch armed rather than falling through, and says why in its own row.

An unset variable falls back to the built-in default.

The variables in Variables with their own parsing rules resolve at their own call sites. Their rows state any differences from these rules.

Variables with their own parsing rules

These variables do not resolve through the chain in Resolution order. Each is read at its own call site with the rule stated here. VAULTSPEC_RAG_ROOT is not a tuning knob at all: it selects the project every entry point addresses, and chains to the framework-wide VAULTSPEC_TARGET_DIR as described above.

The booleans among them accept the same spellings as every other boolean. They differ only in how they resolve a blank value and a word that spells neither state. The Controls column states each one’s rule and the reason for it.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_PREPROCESS	boolean	unset	Kill switch for a root’s preprocessing rules. A false word (0, false, no, off) disables all preprocessing and wins over every other source; a true word, blank, or unset leaves rules enabled; anything else is rejected	--no-preprocess
VAULTSPEC_RAG_STDIO_WATCHDOG	boolean	enabled	Stdio shim self-reap when its spawning process chain breaks. Chains to the framework-wide VAULTSPEC_STDIO_WATCHDOG. Only an explicit 0, false, off, or no disables it; unset, blank, and any unrecognised word all leave it armed, because disarming it by accident strands orphaned shim processes	-
VAULTSPEC_RAG_LOG_LEVEL	string	WARNING	Root logger level, honoured by the CLI, the stdio MCP server, and the resident daemon alike. It resolves over the logging ladder rather than the generic chain, so every process reads one validated answer: VAULTSPEC_RAG_LOG_LEVEL, then the framework-wide VAULTSPEC_LOG_LEVEL, then the process kind’s own default - WARNING for the CLI and the stdio server, INFO for the daemon, whose output is a managed log nobody is watching live. A name no level spells is refused rather than degraded; an invocation-supplied level still outranks the whole ladder	--verbose (INFO), --debug (DEBUG)
VAULTSPEC_RAG_MEMORY_PROBE	boolean	disabled	Diagnostic memory sampler. Follows the standard boolean rule in full, rejection included: unset and blank leave it off, and an unrecognised word is rejected rather than guessed at	-
VAULTSPEC_RAG_ROOT	path	working directory	The project every entry point addresses when nothing else names one. --target outranks it on the CLI and a tool call’s own project_root outranks it over MCP; below it sits the framework-wide VAULTSPEC_TARGET_DIR, then the working directory. A value naming a directory that is not an enrolled workspace fails the run naming the variable, rather than being dropped for a directory that happens to resolve. The resident HTTP service is the exception: it serves every root at once, so both root variables are stripped from its environment at spawn	--target
VAULTSPEC_RAG_MONITOR_BINARY	path	unset	Absolute path to the compiled monitor executable. Unset or empty resolves vaultspec-rag-monitor on PATH. Relative paths and missing executables fail coupled server startup; startup never compiles or downloads the monitor.	-
VAULTSPEC_RAG_TYPESAFE_API_KEY	string	unset	Optional paid Typesafe query classification and full-content result reranking. A credential, never a CLI flag; see Typesafe enrollment	-

Log level. The CLI, the stdio server, and the daemon all read one validated answer. The order is VAULTSPEC_RAG_LOG_LEVEL, then the framework-wide VAULTSPEC_LOG_LEVEL, then the process kind’s own default. That default is WARNING for the CLI and the stdio server, and INFO for the daemon, whose output is a managed log nobody watches live. A level flag on the command line outranks the whole ladder. A name no level spells is refused, not degraded.

Root. --target outranks VAULTSPEC_RAG_ROOT on the CLI, and a tool call’s own project_root outranks it over MCP. Below it sit the framework-wide VAULTSPEC_TARGET_DIR, then the working directory. A value that names a directory that is not an enrolled workspace fails the run and names the variable. The resident HTTP service serves every root at once, so both root variables are stripped from its environment at spawn.

Typesafe key. The server reads the key from its own process environment and never from a CLI flag. A workspace-root .env supplies it only under the credential gate in Resolution order. The resident service is handed the resolved value through its own environment and reads no file itself. Whitespace-only means unset. A valid, funded key authorizes sending queries and candidate content to Typesafe. An absent or unusable key keeps the legacy search. A rejected key (authentication or payment) disables calls for it until you rotate the key or restart the server. A transient failure falls back with a cooldown.

Typesafe enrollment

Set VAULTSPEC_RAG_TYPESAFE_API_KEY in the environment of the account that launches the service. For example, in PowerShell:

Command

$env:VAULTSPEC_RAG_TYPESAFE_API_KEY = '<your-key>'
vaultspec-rag server start
vaultspec-rag server status

For a shell on Linux or macOS, use export VAULTSPEC_RAG_TYPESAFE_API_KEY='<your-key>' before starting the service. Keep the key out of committed files. A workspace-root .env supplies this credential only under the gate described in Resolution order: the running interpreter inside that workspace, and this package’s resolved mode there dependency or dev. It is never read for a globally installed tool. If the server is already running, changing a client shell’s environment does not change that server: restart it from the intended service environment. Scheduled services need the variable in their own launch environment.

Enrollment authorizes paid external processing of search queries and full candidate content. Successful classification can reorder hits and drop confidently irrelevant results, including returning an empty page. Explicit filters still apply. Missing, rejected or temporarily unavailable credentials retain the existing local pipeline. A request the provider’s network edge refuses for its content falls back for that search only; it leaves the key enrolled and does not change the state below.

Both lifecycle commands display a Typesafe: line from the daemon’s /health snapshot; neither command tests the key or spends API credits:

State	Meaning
off	No dedicated key in the server environment; legacy ranking.
pending	Enrolled, but no successful evaluation within the last 60 seconds. The next search checks usability.
active	Enrolled; a validated provider evaluation succeeded within the last 60 seconds. This is observed success, not a live balance check or a promise that every search can be classified.
rejected	Enrolled, but the provider rejected authentication or payment; legacy fallback until key rotation or server restart.
cooldown	Enrolled, but a transient provider failure has temporarily suspended calls; legacy fallback.

An unreachable or older daemon is not reported, not assumed to be enrolled based on the client’s key. In JSON, start returns data.typesafe; status returns data.health.features.typesafe when health is available. The snapshot contains state, model, last_success_age_seconds and retry_after_seconds, never the key or its fingerprint. A key that changed since the last search reads pending until a search evaluates it. A pending/rejected classifier does not make the local search service unhealthy.

For GitHub Actions, store the key as the repository Actions secret VAULTSPEC_RAG_TYPESAFE_API_KEY. Scheduled/manual CI and release validation pass it to the reusable hardware workflow. Its CUDA integration lane runs a live classifier check before GPU provisioning, supplies the key to the service launch and test processes, and refuses to proceed if the running service is not enrolled. A missing or unusable secret fails the live check rather than silently validating only legacy fallback. The secret is not passed to pull-request workflows or accelerator-free unit jobs.

Typesafe connection reuse, caching and diagnostics

The server shares a verified TLS context and up to two exclusive HTTPS connections. Idle sockets expire after 15 seconds. Failed requests are not automatically retried. Successful, validated answers are cached in memory for at most 60 seconds, capped at 128 entries and 4 MiB of response bytes. Keys cover the credential, model, complete request state (including candidate content and filters), and question definitions. Concurrent identical requests share one in-flight call; caches never persist to disk. Key removal, rotation, rejection or a provider cooldown invalidates cached answers. A cached answer reflects the last successful credential check, not a new balance check.

Search responses expose these measurements in timing.phases:

• local_rerank_seconds: local reranker work, excluding hosted candidate calls.

• typesafe_query_attempt_ms: query enrollment/classification elapsed time, including attempts that fall back; typesafe_query_ms reports successful query classification.

• typesafe_rank_ms: elapsed candidate-classification time. Existing rerank_seconds includes both local and hosted candidate work; postprocess_seconds includes reranking.

• typesafe_query_* and typesafe_rank_*: encode_ms, cache_lookup_ms, pool_ms, connect_ms, upload_ms, response_wait_ms, download_ms, validation_ms, request_wait_ms, coalesced_wait_ms and connections_reused, when applicable. Connection time includes DNS/TCP/TLS; response wait includes network and provider processing, not model inference alone. Candidate metrics sum work across overlapping calls and must not be added to elapsed phase times.

• typesafe_requests, typesafe_input_tokens, typesafe_output_tokens: successful network evaluations and their reported usage. Cached/coalesced responses contribute zero new requests or tokens, with separate typesafe_cache_hits and typesafe_coalesced counters. These are not a billing ledger for failed calls.

• classification_fallback_seconds: time spent repeating a direct search through the legacy pipeline after candidate classification fails.

Core variables

The tables in this section list every VAULTSPEC_RAG_* variable resolved through the standard chain.

Backend selection

These variables choose between the supervised Qdrant server (the default) and the on-disk store. They also configure a remote or managed server.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_QDRANT_SERVER	boolean	1 (true)	Server-first default backend	--qdrant / --no-qdrant
VAULTSPEC_RAG_LOCAL_ONLY	boolean	0 (false)	On-disk store opt-out; overrides the server default	--local-only
VAULTSPEC_RAG_QDRANT_PORT	integer	8765	Managed server HTTP port (gRPC binds one below)	-
VAULTSPEC_RAG_QDRANT_URL	string	none	Remote or managed server URL; selects server mode in the store	-
VAULTSPEC_RAG_QDRANT_API_KEY	string	none	Server API key; a managed server uses it in place of a generated one	-
VAULTSPEC_RAG_QDRANT_BINARY	string	none	Absolute path to a binary you supply; requires the digest below	-
VAULTSPEC_RAG_QDRANT_BINARY_SHA256	string	none	SHA256 of that binary; required with the path	-
VAULTSPEC_RAG_QDRANT_STORAGE_DIR	string	~/.vaultspec-rag/qdrant-server/storage	Shared multi-root server storage	-
VAULTSPEC_RAG_QDRANT_QUANTIZATION	string	none	Vector quantization (scalar, turbo, or product)	-
VAULTSPEC_RAG_QDRANT_READY_TIMEOUT	float	300	Seconds of no startup progress the supervisor tolerates (total wait is 4x this)	-
VAULTSPEC_RAG_QDRANT_COLLECTION_LOAD_CONCURRENCY	integer	2	Maximum collections loading concurrently during managed server startup; positive integer	-

Collection load concurrency takes effect on the next managed Qdrant start. Set it to 1 for serial loading; higher values can increase CPU and storage pressure. The managed child translates this setting to Qdrant’s storage.performance.max_concurrent_collection_loads and logs the applied value. It does not configure remote servers or alter shard and segment load concurrency.

Supplying your own server binary

VAULTSPEC_RAG_QDRANT_BINARY and VAULTSPEC_RAG_QDRANT_BINARY_SHA256 are one setting in two halves. Set both to run a Qdrant binary you built or obtained yourself; set neither to use the managed install.

• The path must be absolute and name a regular file.

• The digest is the SHA256 of that file: 64 hexadecimal characters, in either letter case. Print it with Get-FileHash -Algorithm SHA256 <path> on Windows, or sha256sum <path> or shasum -a 256 <path> elsewhere.

• The file is hashed and compared with the digest before every start, including restarts. A file that does not match is never run.

Setting only one of the two is refused, for every command, before the command runs. The message names both variables and repeats the commands above. If you already export VAULTSPEC_RAG_QDRANT_BINARY from an earlier version, export the digest alongside it. The top-level --help and --version still answer while the refusal is in force.

Both are read from the process environment only. A workspace file cannot name a binary for the service to run, and cannot vouch for one.

Managed server provisioning

These variables decide whether a host server start fetches the pinned Qdrant server binary when none is installed, and where it fetches it from. They do not apply to a client installation, which never downloads a binary, or to --local-only, which needs none.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_QDRANT_AUTO_PROVISION	boolean	1 (true)	Download the pinned binary on server start when none resolves; 0 fails with the install command instead	--qdrant-auto-provision / --no-qdrant-auto-provision
VAULTSPEC_RAG_QDRANT_RELEASE_BASE_URL	string	https://github.com/qdrant/qdrant/releases/download	Release base URL; the archive is fetched from {base}/v{version}/{asset}	-
VAULTSPEC_RAG_QDRANT_DOWNLOAD_HOSTS	string	github.com,release-assets.githubusercontent.com,objects.githubusercontent.com	Hosts a download redirect may land on	-

Mirrors. Point VAULTSPEC_RAG_QDRANT_RELEASE_BASE_URL at a mirror that keeps the upstream path layout, so that {base}/v{version}/{asset} resolves. The value must be an https URL with a host. It may carry a port and a path prefix; it may not carry credentials, a query, or a fragment. A trailing slash is ignored.

Host list syntax. VAULTSPEC_RAG_QDRANT_DOWNLOAD_HOSTS is a comma-separated list of host names. Whitespace around an entry is ignored and case does not matter. Each entry is a bare host name: an entry with a scheme, a port, a path, or a wildcard is rejected, and so is a list with no entries. The base URL’s own host always serves the first request, whatever the list says; the list names the hosts that request may be redirected to. A mirror that redirects to its own storage host needs that host listed. Setting the list replaces the default rather than adding to it.

What a mirror cannot change. The download is checked against SHA256 digests compiled into vaultspec-rag. No variable overrides a digest, so a mirror changes where the bytes come from and never which bytes are accepted.

Where these are read from. The process environment only. Like every setting on this page, none of the three is read from a workspace .env or any other file in a project, so a cloned repository cannot choose the server a host downloads an executable from. A value that fails the rules above is rejected at startup with the other unusable settings, before any download begins.

Project and data locations

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_DATA_DIR	path	.vault/data/search-data	Directory holding the on-disk store and index metadata	--data-dir
VAULTSPEC_RAG_QDRANT_DIR	path	qdrant	On-disk store subdirectory inside the data dir	--storage-dir

Service runtime and logging

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_STATUS_DIR	path	~/.vaultspec-rag	Directory for service status, marker, binary, and log files	--status-dir
VAULTSPEC_RAG_LOG_FILE	path	service.log	Resident service log filename inside the status dir	--log-file
VAULTSPEC_RAG_PORT	integer	8766	HTTP service port and MCP fast path	--port
VAULTSPEC_RAG_SERVICE_IDLE_TTL_SECONDS	integer	1800	Seconds an idle project slot stays resident before eviction	-
VAULTSPEC_RAG_SERVICE_MAX_PROJECTS	integer	16	Maximum simultaneously cached project slots	-
VAULTSPEC_RAG_ADMIN_TIMEOUT	float	30	Client connection and read budget for lifecycle and admin calls (seconds)	-
VAULTSPEC_RAG_REINDEX_TIMEOUT	float	900	Client budget for /reindex, which admits every domain before it queues (seconds)	-
VAULTSPEC_RAG_PAUSE_DRAIN_TIMEOUT	float	20	How long a pause waits for in-flight work to drain before it refuses (seconds)	-
VAULTSPEC_RAG_MANAGED_LOG_MAX_BYTES	integer	2097152 (2 MiB)	Active-file size threshold for each managed log source	-
VAULTSPEC_RAG_MANAGED_LOG_BACKUP_COUNT	integer	5	Rotated backups retained for each managed log source	-

The log policy applies independently to service.log and qdrant.log. With the defaults, each source keeps one active file and five backups. The aggregate budget is approximately 24 MiB.

A generation is sized to match the per-source window the log readers scan back over. Raising VAULTSPEC_RAG_MANAGED_LOG_MAX_BYTES past that window keeps bytes that no vaultspec-rag server logs call, MCP log tool, or jobs interface will return: the readers walk back from the newest record and stop at the window, so the head of an oversized generation is written, rotated, and never read. Prefer raising the backup count to hold more history.

Job lifecycle

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_JOB_MAX_NONTERMINAL	integer	64	Maximum simultaneously tracked non-terminal (queued/running) jobs	-
VAULTSPEC_RAG_JOB_SHUTDOWN_TIMEOUT_SECONDS	float	300	Seconds to drain running jobs during a graceful daemon stop	-

Store write resilience

A transient store-write failure (disk pressure, a write-ahead-log stall) is retried with bounded exponential backoff before the operation is abandoned.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_STORE_OPERATION_TIMEOUT_SECONDS	float	120	Per-operation deadline before a store write is abandoned	-
VAULTSPEC_RAG_STORE_WRITE_RETRY_ATTEMPTS	integer	5	Retry attempts for a transient store-write failure	-
VAULTSPEC_RAG_STORE_WRITE_RETRY_BASE_SECONDS	float	0.5	Initial backoff before the first store-write retry	-
VAULTSPEC_RAG_STORE_WRITE_RETRY_MAX_SECONDS	float	8	Maximum backoff between store-write retries	-

Model selection

The stored vectors belong to the model that produced them. After changing any model here, reindex. If the dense width disagrees with the dense model, the store rejects the first upsert rather than writing silently.

Set VAULTSPEC_RAG_SPARSE_ENABLED=0 for dense-only search and rebuild indexes afterwards. The sparse adapter supports only Linkup-Platform/linkup-sparseup-embed-v1; another sparse repository is refused. Dense encoding and reranking still require [gpu] and a supported accelerator.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_EMBEDDING_MODEL	string	Qwen/Qwen3-Embedding-0.6B	Dense embedding model id	-
VAULTSPEC_RAG_EMBEDDING_MODEL_REVISION	string	none	Commit of the dense model; unset uses the compiled-in commit	-
VAULTSPEC_RAG_EMBEDDING_DIMENSION	integer	1024	Dense vector width; must match the dense model	-
VAULTSPEC_RAG_SPARSE_MODEL	string	Linkup-Platform/linkup-sparseup-embed-v1	SPARSEUP sparse model id	-
VAULTSPEC_RAG_RERANKER_MODEL	string	BAAI/bge-reranker-v2-m3	CrossEncoder reranker model id	-
VAULTSPEC_RAG_RERANKER_MODEL_REVISION	string	none	Commit of the reranker model; unset uses the compiled-in commit	-

Pinned models and what is verified

Each default model is pinned twice: to a commit of its repository, and to the SHA256 of every file that commit holds. Both are compiled into vaultspec-rag. The commit says which snapshot is asked for. The digests are what make the answer checkable: a commit is a name the hub resolves, and the hub can be a mirror you configured, so the commit alone says nothing about the bytes that arrive.

A default model’s snapshot is used only when it matches those digests file for file. A missing file, a file that should not be there, and a file with different content are each refused, and the file is named. The check runs when the models are fetched (install, server start, server warmup) and again every time a model is loaded. It reads every byte, about 4 GB for the three default models, and takes a few seconds.

What you configure	Commit used	Reported as	Checked against
Nothing	The compiled-in commit	pinned	The compiled-in digest of every file
A revision variable set to another commit	That commit	unpinned	Its file set and weight format only
A model variable naming another repository	The hub’s default branch	unpinned	Its file set and weight format only
Another repository and its revision variable	That commit	unpinned	Its file set and weight format only

Unset is the pinned state. The two revision variables default to none, and none means the compiled-in commit for a default model. Setting one moves the model to a commit that no compiled-in digest describes, so the model is then reported as unpinned everywhere it is listed. A revision must be a full commit id of 40 hexadecimal characters. A branch or tag name is rejected at startup, because a name that moves would unpin a model while appearing to pin it.

The sparse model has no revision variable. Its repository ships the code that builds the model, and vaultspec-rag runs that code. The code is covered by the compiled-in digests and is loaded from the very bytes that were checked. A commit the environment could change would select code no digest covers, so there is no setting for it.

Weights are safetensors only, for every model. A model that ships its weights only in a pickle format is refused with that reason, because loading a pickle file runs code from whatever served it. No model is given permission to run code from its repository.

An unpinned model still works. It is fetched, checked for a configuration file, a tokenizer and safetensors weights, and loaded. Once cached it is not refreshed by a later start. What it lacks is any check of its content, and server doctor, install, server start and server warmup say so wherever they list it.

Proving the cache without starting the service. vaultspec-rag server doctor hashes each pinned model’s snapshot and reports the result. A failed check names the model and the file. vaultspec-rag server warmup repairs it: a file that fails is downloaded again once. If it still fails, the hub is not serving the pinned release; check VAULTSPEC_RAG_HF_ENDPOINT.

A model load never downloads. Models are fetched by install, by server warmup, and by the check server start runs before it launches the service. The service, and every other process that loads a model, reads the cache only. When a model is absent or fails its check, the load stops with one message: the model, what is wrong with it, and what to run. That is vaultspec-rag server warmup for a model or file that is missing, server warmup and then vaultspec-rag server doctor for a file that fails its digest, and server doctor alone, after removing the file, for a file that does not belong. The dense model, the sparse model and the reranker all fail this way, whenever each first loads.

While a model loads on Windows, every file of its snapshot is held open against writing, deleting and renaming from before it is hashed until the load has finished. Other platforms offer no such hold: a process that can write the model cache could replace a file between the check and the load. Because weights are safetensors and the sparse model’s code is loaded from the checked bytes, such a replacement could change a model’s numbers but could not run code.

The ONNX dense backend is not used with a pinned model. The pinned release contains no ONNX graph, and a graph made or placed locally would be a file no digest covers. With VAULTSPEC_RAG_DENSE_BACKEND=onnx and the default dense model, vaultspec-rag logs a warning and uses the torch backend.

Model download source

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_HF_ENDPOINT	string	https://huggingface.co	Model hub the dense, sparse and reranker models are downloaded from	-
VAULTSPEC_RAG_MODEL_FETCH_DEADLINE_SECONDS	float	14400	Longest one model fetch may take, every repository together	-

Set this to download models from a hub mirror. The value must be an https URL with a host. It may carry a port and a path prefix; it may not carry credentials, a query, or a fragment. A mirror must keep the hub’s path layout.

Set it before the process starts. The Hugging Face Hub client reads its endpoint once, when it is first loaded, so vaultspec-rag exports this value to HF_ENDPOINT at the start of every process: the CLI, the stdio MCP server, and the resident service. The resident service inherits it from the command that starts it. Changing the variable in a shell does not move a service that is already running; restart it from the intended environment.

Precedence. VAULTSPEC_RAG_HF_ENDPOINT wins when it is set. Otherwise an HF_ENDPOINT you set yourself is left exactly as it is, and the Hub client judges it by its own rules. With neither set, the Hub client’s default applies, which is the same https://huggingface.co. An unset or blank VAULTSPEC_RAG_HF_ENDPOINT exports nothing.

Like every setting on this page, it is read from the process environment only, never from a workspace .env.

Embedding and reranking

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_EMBEDDING_BATCH_SIZE	integer	64	Outer batch size fed to the embedding pipeline	-
VAULTSPEC_RAG_EMBEDDING_ENCODE_BATCH_SIZE	integer	32	Vault inner encode sub-batch size	-
VAULTSPEC_RAG_EMBEDDING_CODE_ENCODE_BATCH_SIZE	integer	32	Code inner encode sub-batch size	-
VAULTSPEC_RAG_EMBEDDING_DOCUMENT_ENCODE_BATCH_SIZE	integer	12	Document inner encode sub-batch size	-
VAULTSPEC_RAG_EMBEDDING_ENCODE_TOKEN_BUDGET	integer	24000	Estimated padded token footprint allowed per dense encode bucket	-
VAULTSPEC_RAG_EMBEDDING_SPARSE_ENCODE_TOKEN_BUDGET	integer	24000	Estimated padded token footprint allowed per sparse encode bucket	-
VAULTSPEC_RAG_EMBEDDING_ENCODE_CHARS_PER_TOKEN	integer	3	Chars-per-token ratio used to plan encode buckets	-
VAULTSPEC_RAG_EMBEDDING_MAX_SEQ_LENGTH	integer	2048	Hard cap on sequence length advertised to the model	-
VAULTSPEC_RAG_MAX_EMBED_CHARS	integer	8000	Character cap applied to each text before encoding	-
VAULTSPEC_RAG_RERANKER_MAX_LENGTH	integer	1024	Reranker token bound	-
VAULTSPEC_RAG_RERANKER_BATCH_SIZE	integer	32	Candidate pairs per reranker forward pass	-
VAULTSPEC_RAG_VAULT_CHUNK_CHARS	integer	3000	Vault chunk character budget	-
VAULTSPEC_RAG_DOCUMENT_CHUNK_CHARS_PER_TOKEN	integer	3	Chars-per-token ratio turning the model’s token window into a document chunk budget	-
VAULTSPEC_RAG_DOCUMENT_CHUNK_OVERLAP_CHARS	integer	256	Overlap carried across a document chunk boundary	-

Indexing

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_INDEX_CHUNK_WORKERS	integer	0 (auto)	Code-chunk process-pool size	-
VAULTSPEC_RAG_INDEX_PARALLEL_MIN_BYTES	integer	8388608 (8 MiB)	Auto-parallel chunking threshold in bytes	-
VAULTSPEC_RAG_INDEX_REUSE	boolean	1 (true)	Reuse sibling-namespace vectors across worktrees	-
VAULTSPEC_RAG_INDEX_CACHE_FLUSH_SLICES	integer	8	CUDA allocator flush cadence on the codebase encode path, in slices	-
VAULTSPEC_RAG_VAULT_CACHE_FLUSH_SLICES	integer	1	CUDA allocator flush cadence on the vault encode path, in slices	-
VAULTSPEC_RAG_DOCUMENT_CACHE_FLUSH_SLICES	integer	1	CUDA allocator flush cadence on the document encode path, in slices	-
VAULTSPEC_RAG_DENSE_BACKEND	string	torch	Dense encoder backend (onnx experimental)	-
VAULTSPEC_RAG_DENSE_ONNX_FILE	string	onnx/model_O4.onnx	ONNX model file relative path	-

Index resource bounds and memory ceilings

These bound the segment and queue geometry of one index run, its memory use, and its liveness. The defaults suit a managed multi-root service; lower them on a smaller host. Every memory figure here is in mebibytes (MiB).

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_INDEX_SEGMENT_MAX_CHUNKS	integer	64	Chunks per index upsert segment	-
VAULTSPEC_RAG_INDEX_SEGMENT_MAX_BYTES	integer	8388608 (8 MiB)	Byte cap per index upsert segment	-
VAULTSPEC_RAG_INDEX_QUEUE_MAX_CHUNKS	integer	512	Chunks buffered in the producer-to-consumer index queue	-
VAULTSPEC_RAG_INDEX_QUEUE_MAX_BYTES	integer	134217728 (128 MiB)	Byte cap on the buffered index queue, applying backpressure	-
VAULTSPEC_RAG_INDEX_NO_PROGRESS_TIMEOUT_SECONDS	float	900	Seconds without index progress before the run is failed	-
VAULTSPEC_RAG_INTEGRITY_AUTO_REPAIR	boolean	0 (false)	Queue one failure-safe reindex when a search finds the served index shrunken below its published claim	-
VAULTSPEC_RAG_INDEX_RSS_CEILING_MIB	float	16384	Resident-memory ceiling enforced at index checkpoints (MiB)	-
VAULTSPEC_RAG_INDEX_CUDA_CEILING_MIB	float	0 (auto-derive)	CUDA-memory ceiling override in MiB; 0 derives one from the device	-
VAULTSPEC_RAG_INDEX_CUDA_HEADROOM_MIB	float	2048	Memory reserved below the device total when the ceiling auto-derives (MiB)	-
VAULTSPEC_RAG_INDEX_CUDA_ALLOCATOR_FRACTION	float	0.8	Fraction of CUDA memory the index allocator may reserve	-
VAULTSPEC_RAG_GPU_ADMISSION_FLOOR_MIB	integer	0 (auto-derive)	Free device memory required before this process loads model stacks (MiB)	-
VAULTSPEC_RAG_INDEX_SUPPORT_PROFILE	string	managed-service	Index resource profile advertised to the service; managed-service or embedded-local	-

How the CUDA ceiling and admission floor derive

The CUDA ceiling derives from the real device rather than shipping fixed. At 0 the ceiling is the device’s total memory minus VAULTSPEC_RAG_INDEX_CUDA_HEADROOM_MIB, so a larger card gets a larger budget without tuning. A positive value overrides that.

The ceilings bound the work an already-resident process does. VAULTSPEC_RAG_GPU_ADMISSION_FLOOR_MIB answers the question before it: whether this process may bring a model stack up at all. The process reads the floor once, before the first load. If the card has less free memory than the floor, the load is refused, and the message names both the reading and the floor.

The floor also derives by default. At 0 it comes from the CUDA demand the configured support profile declares, so it tracks the workload rather than one machine’s measurements. It does not read the device. Model weights occupy what they occupy on any card, so what a load needs is a property of the models, not the hardware. A figure calibrated to one card would refuse every load on a smaller one and under-protect a larger. A positive value overrides the derivation.

A floor has to cover the resident stack a load creates, plus the largest demand that stack then places on top of its own residency. Sizing it to the resident stack alone is not enough: on a card already holding one tenant, the leftover free memory still clears such a floor, so a second stack is admitted onto a device that cannot hold both. Setting it too high refuses loads the card could have served, and a floor above a small card’s total memory refuses every load.

Concurrency limits

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_SEARCH_CONCURRENCY	integer	16	Search worker limiter	-
VAULTSPEC_RAG_INDEX_JOB_CONCURRENCY	integer	4	Index job limiter	-

Search and model toggles

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_SPARSE_ENABLED	boolean	1 (true)	SPARSEUP sparse vectors on/off	-
VAULTSPEC_RAG_VAULT_INTENT_DEFAULT	string	orientation	Default vault ranking intent when a search names none (orientation or debugging)	-
VAULTSPEC_RAG_VAULT_INTENT_RANKING_ENABLED	boolean	1 (true)	Intent-aware vault re-ranking on/off (0 restores the bare-reranker ordering)	-
VAULTSPEC_RAG_VAULT_INTENT_TYPE_CAP	integer	4	Maximum results of one doc type on a vault page (0 disables the cap)	-
VAULTSPEC_RAG_RERANKER_ENABLED	boolean	1 (true)	CrossEncoder rerank on/off	-
VAULTSPEC_RAG_SEARCH_TIMEOUT	float	300	Client connection and read budget for service-handled searches (seconds)	--timeout
VAULTSPEC_RAG_SEARCH_FRESHNESS_WAIT_MAX_SECONDS	float	30	Maximum bounded wait accepted for search freshness (seconds)	--freshness-wait-seconds
VAULTSPEC_RAG_CODE_NOISE_HIDE_DOMAINS	string	worktree,generated	Code domains hidden from results by default	-
VAULTSPEC_RAG_CODE_NOISE_DEMOTE_DOMAINS	string	tests,docs,locale,vendored	Code domains demoted (not hidden) by default	-
VAULTSPEC_RAG_CODE_NOISE_DEMOTE_PENALTY	float	0.3	Score subtracted from a demoted code result	-
VAULTSPEC_RAG_DEDUP_LOCALES_DEFAULT	boolean	1 (true)	Collapse locale-variant code results by default	--dedup-locales / --no-dedup-locales
VAULTSPEC_RAG_GRAPH_TTL_SECONDS	float	300	Vault graph cache lifetime backing link and grounding lookups (seconds)	-

Automatic updates

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_WATCH_ENABLED	boolean	1 (true)	Filesystem auto-reindex on/off (0 = pull-only)	--updates / --no-updates
VAULTSPEC_RAG_WATCH_DEBOUNCE_MS	integer	2000	Compatibility input mapped to both adaptive coalescing bounds (ms)	--update-delay-ms
VAULTSPEC_RAG_WATCH_COOLDOWN_S	float	30	Compatibility input mapped to the adaptive cooling maximum (s)	--repeat-update-delay-s

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_WATCH_COALESCE_MIN_SECONDS	float	2	Minimum adaptive coalescing delay	-
VAULTSPEC_RAG_WATCH_COALESCE_MAX_SECONDS	float	30	Maximum adaptive coalescing delay; cannot exceed maximum freshness	-
VAULTSPEC_RAG_WATCH_COOLING_MAX_SECONDS	float	120	Maximum post-success adaptive cooling delay	-
VAULTSPEC_RAG_WATCH_MAXIMUM_FRESHNESS_SECONDS	float	300	Oldest ordinary-pressure event age before admission	-
VAULTSPEC_RAG_WATCH_MEASUREMENT_REEVALUATION_SECONDS	float	5	Maximum interval between service-measurement reevaluations	-
VAULTSPEC_RAG_WATCH_BATCH_PATH_LIMIT	integer	10000	Pending path count that makes work ready; cannot exceed scope path limit	-
VAULTSPEC_RAG_WATCH_SCOPE_MAX_PATHS	integer	100000	Maximum durable exact paths per controller	-
VAULTSPEC_RAG_WATCH_SCOPE_MAX_BYTES	integer	8388608 (8 MiB)	Maximum serialized durable exact-scope size per controller	-

A failed auto-reindex retries with exponential backoff and a circuit breaker that stops retrying a persistently failing source.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_WATCH_RETRY_BASE_SECONDS	float	30	Initial backoff before retrying a failed auto-reindex	-
VAULTSPEC_RAG_WATCH_RETRY_MAX_SECONDS	float	1800	Maximum backoff between auto-reindex retries	-
VAULTSPEC_RAG_WATCH_RETRY_JITTER_FRACTION	float	0.1	Random jitter fraction added to each retry backoff	-
VAULTSPEC_RAG_WATCH_CIRCUIT_FAILURE_THRESHOLD	integer	3	Consecutive failures before the watch circuit opens	-

Storage maintenance (auto-prune)

These variables control the daemon’s scheduled storage-maintenance cycle. See the storage and maintenance guide for how a cycle runs.

Zero means opposite things on the two kinds of window here, so read the names carefully. The three GRACE_HOURS* windows are how long a namespace has to stay observably dead before it may be destroyed; they are rejected below 1 hour, because at zero the cycle that first sees a namespace would also be allowed to drop it. EPHEMERAL_IDLE_HOURS is a tier’s own on/off switch, and zero turns that tier off. So ..._EPHEMERAL_IDLE_HOURS=0 reclaims nothing, while a zero on ..._GRACE_HOURS_EPHEMERAL would have reclaimed everything on sight - which is why only the idle knob accepts it.

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_STORAGE_AUTOPRUNE	boolean	1 (true)	Scheduled auto-prune on/off (server mode only)	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_INTERVAL_MINUTES	float	60	Minutes between maintenance cycles	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_GRACE_HOURS	float	24	Continuous-orphan hours before an empty namespace is reclaimed (minimum 1)	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_GRACE_HOURS_DATA	float	168	Continuous-orphan hours before a point-bearing namespace is archived and reclaimed (minimum 1)	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_GRACE_HOURS_EPHEMERAL	float	24	Continuous-orphan hours before a temp-rooted namespace is reclaimed, whatever it holds (minimum 1; NOT the idle knob below)	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_ARCHIVE_RETENTION_DAYS	float	30	Days a snapshot archive is kept before the retention sweep deletes it	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_ARCHIVE_MAX_GB	float	64	Total-size cap on the archive directory (oldest evicted first)	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_MAX_PER_CYCLE	integer	16	Maximum namespaces reclaimed per cycle	-
VAULTSPEC_RAG_STORAGE_AUTOPRUNE_EPHEMERAL_IDLE_HOURS	float	72	Idle hours before a live temp-rooted namespace is reclaimed (0 disables this tier)	-
VAULTSPEC_RAG_STORAGE_RECONCILE	boolean	1 (true)	Shrink pre-existing collections onto the bounded segment geometry	-
VAULTSPEC_RAG_STORAGE_RECONCILE_MAX_PER_CYCLE	integer	4	Maximum collections reconciled per cycle	-
VAULTSPEC_RAG_STORAGE_RECONCILE_BUDGET_SECONDS	float	300	Per-collection wait for the merge to settle before reporting	-

Preprocessing

Variable	Type	Default	Controls	CLI flag
VAULTSPEC_RAG_PREPROCESS_MAX_EMITTED_BYTES	integer	10485760 (10 MiB)	Cap on text a preprocess hook may emit per file, in bytes	-
VAULTSPEC_RAG_HTML_STRIP	boolean	1 (true)	Strip tags from .html to plain text before chunking	-

Config-only keys

These keys exist in the configuration loader and take no direct environment override of their own. Where the environment still reaches one, it does so through a variable that resolves at its own call site, listed in Variables with their own parsing rules.

Config key	Type	Default	Controls
log_level	string	WARNING	Root logger level; the environment reaches it through the VAULTSPEC_RAG_LOG_LEVEL ladder rather than a direct override
preprocess_mode	string	default	Two-state preprocessing mode; the environment reaches it through VAULTSPEC_RAG_PREPROCESS rather than a direct override

Hugging Face cache

vaultspec-rag downloads its dense, sparse, and reranker model files through the Hugging Face Hub. These are third-party variables (no VAULTSPEC_RAG_ prefix), so they sit outside the reference tables on this page. The Hub client honours most of them itself; the Controls column notes where vaultspec-rag reads or defaults one itself.

Variable	Type	Controls
HF_HOME	path	Hub cache root. Read directly when reporting cache location; falls back to ~/.cache/huggingface
HF_HUB_CACHE	path	Directory the model snapshots are kept in, in place of the one under HF_HOME
HF_ENDPOINT	string	Hub endpoint. VAULTSPEC_RAG_HF_ENDPOINT overwrites it at process start when set
HF_HUB_DOWNLOAD_TIMEOUT	integer	Hub client’s per-read timeout in seconds. vaultspec-rag does not set it; the default is 10
HF_HUB_OFFLINE	boolean	Offline mode; no model is fetched from the Hub
TRANSFORMERS_OFFLINE	boolean	Transformers’ offline switch; same effect
DISABLE_SAFETENSORS_CONVERSION	boolean	Skip on-the-fly safetensors conversion

All default models download publicly, without account setup. To omit sparse encoding, set VAULTSPEC_RAG_SPARSE_ENABLED=0 in the service environment and rebuild existing indexes. The service still needs [gpu] and a supported GPU.

HF_HOME sets where model files are cached, and defaults to ~/.cache/huggingface. Set it to a persistent location before the first download.

HF_HUB_DOWNLOAD_TIMEOUT is the Hub client’s per-read timeout: the seconds it waits with no data arriving before it abandons one download attempt. It is not a budget for a whole file. vaultspec-rag does not set it, so the client’s default of 10 applies. The client retries a file up to five more times and starts that count again whenever data arrives, so a hub that goes silent fails a file after about a minute. Raise it for a link that pauses for longer than that.

HF_HUB_OFFLINE is the authoritative offline switch; vaultspec-rag also honours TRANSFORMERS_OFFLINE. When either is set to 1, true, yes, or on, install, server start and server warmup fetch no model and report what the cache lacks. Loading a model never fetches one, whether or not they are set. See the Hugging Face environment variable reference.

Searches additionally quiet the Hub and Transformers loggers by defaulting HF_HUB_DISABLE_PROGRESS_BARS, TRANSFORMERS_NO_ADVISORY_WARNINGS, and TRANSFORMERS_VERBOSITY when they are unset. Set them yourself to keep the library output.

HF_ENDPOINT is the Hub client’s own endpoint variable. Setting it directly still works. VAULTSPEC_RAG_HF_ENDPOINT outranks it; see Model download source.

Download sources

vaultspec-rag downloads three things on its own. This table says where each one comes from and what moves it.

What	Default source	How to change it
Managed Qdrant server binary	https://github.com/qdrant/qdrant/releases/download	VAULTSPEC_RAG_QDRANT_RELEASE_BASE_URL and VAULTSPEC_RAG_QDRANT_DOWNLOAD_HOSTS; see Managed server provisioning
Dense, sparse, reranker models	https://huggingface.co	VAULTSPEC_RAG_HF_ENDPOINT; see Model download source
CUDA build of PyTorch	https://download.pytorch.org/whl/cu130	No variable; edit the index entry in your own pyproject.toml

The CUDA wheel index has no variable, on purpose. vaultspec-rag install writes that index into a project’s pyproject.toml as a [[tool.uv.index]] entry named pytorch-cu130, and uv reads the file from then on. The URL is therefore a value committed to a repository, not a setting of the running process, and an environment variable could not make it consistent across the people and jobs that share the file. To use a wheel mirror, change the url of that entry by hand. vaultspec-rag then treats the block as customised and never rewrites or removes it. The installation guide shows the entry.

Renamed and removed variables

If a setting stopped taking effect after an upgrade, look for its old name here. A stale name sets nothing: the value falls back to the default rather than failing loudly, so nothing tells you at startup.

Three memory ceilings changed their unit suffix from MB to MIB. The old spellings are no longer read at all. Rename them wherever they are set, in an .env file, a supervisor unit, or a continuous integration job:

• VAULTSPEC_RAG_INDEX_RSS_CEILING_MB is now VAULTSPEC_RAG_INDEX_RSS_CEILING_MIB

• VAULTSPEC_RAG_INDEX_CUDA_CEILING_MB is now VAULTSPEC_RAG_INDEX_CUDA_CEILING_MIB

• VAULTSPEC_RAG_INDEX_CUDA_HEADROOM_MB is now VAULTSPEC_RAG_INDEX_CUDA_HEADROOM_MIB

The same rename applies to the JSON any script reads off the health, status, jobs, and diagnostics surfaces. Every _mb field is now _mib, including gpu_memory_used_mb, gpu_memory_total_mb, rss_ceiling_mb, and cuda_ceiling_mb. No value changed. These were always mebibytes, and only the spelling moved.

Tuning for memory and speed

Dense and sparse encoders plan batches under independent padded-token budgets. A CUDA out-of-memory error lowers the affected encoder’s learned budget and retries only the failing bucket, down to one item. Recovery requires successful buckets that exercise the learned ceiling; short batches cannot certify a larger allocation. The knobs below reduce memory pressure before that automatic backoff engages, or raise throughput.

The two ceilings behave differently from that backoff, and it is worth knowing which is which. VAULTSPEC_RAG_INDEX_RSS_CEILING_MIB and VAULTSPEC_RAG_INDEX_CUDA_CEILING_MIB are not throttles: they are checked at index checkpoints, and a reading above one fails the run with rss_memory_ceiling or cuda_memory_ceiling. The first breach is latched, so the outcome does not change if a later sample recovers.

Their defaults are single-tenant. The resident-memory ceiling ships at 16384 MiB, which is the same 16 GiB the installation guide states as the minimum for the default profile, so on a machine sized to that floor one index run may claim all of it. On a host shared with anything else - another tenant, a build, a second project’s run - set both ceilings to what you can actually spare rather than leaving the defaults.

To fit a smaller GPU:

• For long code batches, try VAULTSPEC_RAG_EMBEDDING_SPARSE_ENCODE_TOKEN_BUDGET=8192 independently of the dense budget (24000). At the sparse model’s 512-token document limit, this permits sixteen items; short documents can still fill the 32-item cap. Measure indexing time and device power before adopting the setting for your workload.

• Lower the inner encode sub-batches: VAULTSPEC_RAG_EMBEDDING_ENCODE_BATCH_SIZE and VAULTSPEC_RAG_EMBEDDING_CODE_ENCODE_BATCH_SIZE (32 each), and VAULTSPEC_RAG_EMBEDDING_DOCUMENT_ENCODE_BATCH_SIZE (12, smaller because document fragments fill the model’s whole window).

• Cap VAULTSPEC_RAG_EMBEDDING_MAX_SEQ_LENGTH (default 2048) to shrink padded-attention memory.

• Raise VAULTSPEC_RAG_INDEX_CUDA_HEADROOM_MIB to leave more of the device outside the indexing budget, or set VAULTSPEC_RAG_INDEX_CUDA_CEILING_MIB to pin an explicit ceiling.

• Set VAULTSPEC_RAG_QDRANT_QUANTIZATION to scalar to compress the stored vectors.

• Turn off a model to free the most memory. Set VAULTSPEC_RAG_SPARSE_ENABLED=0 to drop the SPARSEUP encoder, or VAULTSPEC_RAG_RERANKER_ENABLED=0 to drop the CrossEncoder.

To speed up indexing:

• Raise VAULTSPEC_RAG_INDEX_CHUNK_WORKERS (0 auto-sizes to the CPU count, 1 forces serial).

• Lower VAULTSPEC_RAG_INDEX_PARALLEL_MIN_BYTES so the process pool engages on smaller trees.

• Raise VAULTSPEC_RAG_INDEX_JOB_CONCURRENCY (default 4) if the host has spare cores.

Each variable’s default and meaning is listed in the preceding variable tables.

Examples

Point a single command at another project:

Command

vaultspec-rag --target /srv/projects/acme search "billing flow"

Bind the HTTP service to a non-default port:

Command

VAULTSPEC_RAG_PORT=9100 vaultspec-rag server start

Run the on-disk store instead of the supervised server. The default index profile accepts only the server backend, so select the embedded-local profile too:

Command

VAULTSPEC_RAG_LOCAL_ONLY=1 VAULTSPEC_RAG_INDEX_SUPPORT_PROFILE=embedded-local vaultspec-rag server start

Raise the log level to DEBUG for one command:

Command

vaultspec-rag --debug search "billing flow"

Where to go next

See the Support section of the repo README.