Copy page View as Markdown

TypeSafe API integration and environment loading

TypeSafe is optional. Core and RAG each read their own API key for their hosted features. Installing Core and managing records needs neither.

Which source wins?

Your shell, agent, and service each have their own process environment. User/system environment settings reach Vaultspec through that process; they are not extra files Vaultspec searches. Supply settings to the process that runs it.

Core and RAG resolve settings in one shared order. The first source that supplies a value wins:

Source	Core reads	RAG reads
The invocation	Command flags	Command flags
Process environment	Every setting	Every setting; scoped names first
Project store .vaultspec/.env	Settings imported by install	Nothing
Workspace-root .env	VAULTSPEC_CORE_TYPESAFE_API_KEY, when eligible	VAULTSPEC_RAG_TYPESAFE_API_KEY, when eligible
Persisted configuration	.vaultspec/config.toml or .vaultspec/workspace.json	The saved local-only backend choice
Default	Built-in	Built-in

“Eligible” means the running Python interpreter lives inside that workspace’s own environment, and the reading package is installed there in dev or dependency mode. A uv tool, a pipx install, or a release binary pointed at the project never reads its .env. No other name is read from that file, and nothing is read from .env.local or a parent directory’s .env.

A blank value counts as unset and falls through to the next source. An invalid nonblank value for a Vaultspec variable refuses the run with exit code 1, listing every unusable setting at once (as an error envelope under --json):

Captured output

Error: VAULTSPEC_JSON_PRETTY must be one of 0, 1, false, no, off, on, true, yes, got 'maybe'

The stdio watchdog switch is the exception: an unrecognised value leaves it armed. For every variable and its rules, see Core’s settings resolution and environment variables, and RAG’s resolution order.

Shared framework names

Three RAG settings read RAG’s own name first and fall back to the name Core reads, so one exported value configures both:

RAG variable	Falls back to
VAULTSPEC_RAG_ROOT	VAULTSPEC_TARGET_DIR
VAULTSPEC_RAG_LOG_LEVEL	VAULTSPEC_LOG_LEVEL
VAULTSPEC_RAG_STDIO_WATCHDOG	VAULTSPEC_STDIO_WATCHDOG

A blank RAG value falls through to the shared name. Credentials never fall back.

Keep the keys separate

Component	Variable	Enables
Core	VAULTSPEC_CORE_TYPESAFE_API_KEY	Hosted vault search, ADR cross-referencing, and optional context ranking
RAG	VAULTSPEC_RAG_TYPESAFE_API_KEY	Query classification and result reranking

Setting the generic TYPESAFE_API_KEY or the RAG key does not enable Core, and Core’s key does not enable RAG.

Keep credentials out of committed files. Treat hosted features as external processing: Core sends the question and vault text to TypeSafe, and RAG sends queries and candidate content. Read what Core’s vault search and RAG’s TypeSafe enrollment send before enabling them for sensitive content.

Core

During install and upgrade

Package acquisition (uv tool install, uv add, or a binary download) makes the commands available. vaultspec-core install and install --upgrade provision project files from that package. They do not upgrade it.

Set process environment variables before running either provisioning command. Exporting a variable affects that process but does not automatically save it in the project. The workspace-root .env still follows the credential-only eligibility rules above, including during a first install.

Core validates --env and --env-file imports before provisioning, then merges them into .vaultspec/.env after the resource installation succeeds. Explicit --env entries override values from --env-file; supplied names replace their stored values and unmentioned names remain unchanged. A dry run reports the proposed imports without writing them.

An import does not export variables into the running process or change its already-selected target, provider, or launch mode. Stored settings apply to later commands; the final output can already reflect imported JSON formatting and hint settings. Process environment values continue to override the store.

Store Core settings in the project

install can import a supported setting into the project store, .vaultspec/.env, which the installer adds to .gitignore:

Command

uvx vaultspec-core install --env VAULTSPEC_CORE_TYPESAFE_API_KEY

That imports the key by name from the process environment, so its value never appears on the command line. --env-file PATH imports from a dotenv file instead. On an existing installation, add --upgrade; without it the install is refused. Passing a secret as --env NAME=VALUE is refused without echoing it, and a name outside the supported list is refused. See install for the supported names.

The project store works in every Core provisioning mode, including tool. It is separate from the workspace-root .env, whose eligibility is narrower. A running MCP server keeps the process environment it started with; restart it after changing that environment.

Check what Core found

Check Core’s configuration without making a hosted request. Use the prefix that matches your installation mode:

Command

uvx vaultspec-core status --json
uv run vaultspec-core status --json

data.hosted_search reports configured and source: environment, local_env (the project store), or dotenv (the workspace-root .env). A configured key has been found; this does not establish that TypeSafe accepts it.

Without a key, vaultspec-core vault search "<question>" --json sends nothing and exits 0 with envelope status: "skipped", data.status: "not_configured", and a data.next_step naming the search to run instead. It does not run that command for you. With a key present, it attempts hosted search.

RAG: set the key where the service starts

Set VAULTSPEC_RAG_TYPESAFE_API_KEY in the environment that runs vaultspec-rag server start. The service receives the key resolved at start rather than reading a file itself, so a key in the project’s .env reaches it only when server start runs from an eligible project environment. The Qdrant API key is never read from .env.

RAG has no Core-style --env or --env-file import, and does not read Core’s project store. Export operational settings before both repository setup and service startup when they need to apply to both. Restart the service after changing its settings; changing a client shell does not update a running service. The default models are public and need no HF_TOKEN; RAG does not load that name from the workspace-root .env.

See RAG configuration for the full component reference.

Verification limits

These checks used synthetic credentials in throwaway projects on Windows. No funded TypeSafe credential was available, so successful paid API responses and hosted ranking quality were not verified. The examples establish local configuration behavior, not successful API authentication.