--- generator: "vaultspec-marketing discovery" title: "TypeSafe API integration and environment loading - Vaultspec documentation" description: "TypeSafe is optional. Core and RAG each read their own API key for their hosted features. Installing Core and managing records needs neither." url: "https://vaultspec.neve.md/docs/guides/typesafe-env.html" component: "site" date_modified: "2026-10-08T14:11:28+02:00" --- [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** ```text 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** ```sh 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** ```sh 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 "" --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.