--- generator: "vaultspec-marketing discovery" title: "Set up vaultspec-rag - vaultspec-rag documentation" description: "vaultspec-rag adds search by meaning over project records and code." url: "https://vaultspec.neve.md/docs/rag/installation.html" component: "vaultspec-rag" --- [View as Markdown]() # Set up vaultspec-rag vaultspec-rag adds search by meaning over project records and code. It is optional for [Core](), but the workflow is designed around it: agents look for evidence by meaning first. vaultspec-rag depends on Core, so every installation below installs Core with it; it also searches repositories that don’t use the workflow. The search service needs a supported graphics processor (GPU): an NVIDIA GPU with CUDA on Linux or Windows, or Apple silicon on macOS. It doesn’t run on the CPU or on AMD GPUs, and no route supports Intel Macs. [Why it needs a GPU]() explains the choice. ## Choose what this environment runs Each machine runs one background search service, started under your user account. Two kinds of installation work with it: - A **host installation** carries the `gpu` extra. It runs the models and is the only kind that can start the service. - A **client installation** leaves `gpu` out. It loads no models, needs no GPU, and sends every request to the service a host installation on the same machine started. It must be exactly the service’s release; a client refuses any other. The `mcp` extra adds the server your coding agent launches. Extras are not `--mode` flags. ### Choose an installation | Package | Installation | Starts the service | Runs the agent’s MCP server | | --- | --- | --- | --- | | `vaultspec-rag` | Client | No | No | | `vaultspec-rag[mcp]` | Client | No | Yes | | `vaultspec-rag[gpu]` | Host | Yes | No | | `vaultspec-rag[gpu,mcp]` | Host | Yes | Yes | Every machine needs one host installation. If `vaultspec-rag server status` already reports the service running, [set up each repository]() from that host installation, or [add a client]() to a Python project. If it reports the service stopped, start it with `vaultspec-rag server start` rather than reinstalling. ## What you need before you start For a host installation: - On Linux or Windows, an NVIDIA driver that supports CUDA 13: the `CUDA Version` that `nvidia-smi` prints must be 13.0 or later. On macOS, the system provides the driver. - For the default resource profile, 16 GiB of system RAM, 8 GiB of free index-store space, and 12 GiB of free CUDA memory at startup. The `embedded-local` profile lowers these for smaller corpora; select it with `VAULTSPEC_RAG_INDEX_SUPPORT_PROFILE` in the environment that starts the service ([resource bounds]()). - Several gigabytes of free disk for the models, which every repository shares. - [uv]() and CPython 3.13 or 3.14 for the Python routes. A prebuilt binary needs neither. - Network access to PyPI, `download.pytorch.org` on Linux and Windows, the Hugging Face model server, and GitHub release downloads. On Apple silicon the service uses Metal Performance Shaders (MPS) and refuses to start while `PYTORCH_ENABLE_MPS_FALLBACK` lets operations fall back to the CPU, so unset it where the service starts. ### The model cache and its first download The default dense, sparse, and reranking models are public. They need no Hugging Face account, login, or token. The sparse model is `Linkup-Platform/linkup-sparseup-embed-v1` (SPARSEUP). Set `HF_HOME` in the process environment before provisioning if you want a different model-cache location. Repository setup and host service startup can fetch missing files; clients never download them. See [model and index-server provisioning]() for the pinned downloads, cache verification, and offline setup. ## Set up a host installation ### Install as a standalone tool This is the default route. One installation serves every repository on the machine. On Windows x86-64 and Linux x86-64 or aarch64: **Command** ```sh uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" --index https://download.pytorch.org/whl/cu130 --index-strategy unsafe-first-match ``` On Apple silicon: **Command** ```sh uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" ``` The two index options fetch CUDA PyTorch, and uv records them so later upgrades keep the GPU build. A tool installed without them gets CPU-only PyTorch; repair it with [pin the GPU build](). If uv says its executables directory isn’t on your `PATH`, run `uv tool update-shell` and open a new terminal. ### Install as a project dependency Choose this when one Python project’s environment should run the service and collaborators share its pinned release. Configure the CUDA build of PyTorch before you add the package. Otherwise the first `uv add` installs PyPI’s `torch`, which is CPU-only on Windows. Add this block to the project’s `pyproject.toml`; it’s the same block the repository setup writes: **File contents** ```toml [[tool.uv.index]] name = "pytorch-cu130" url = "https://download.pytorch.org/whl/cu130" explicit = true [tool.uv.sources] torch = [ {index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'"}, ] ``` Then, from the project root, add vaultspec-rag together with `torch` as a direct dependency, because uv applies a package source only to direct dependencies: **Command** ```sh uv add "vaultspec-rag[gpu,mcp]" "torch>=2.4" ``` Linux and Windows get the CUDA build, and Apple silicon gets the standard build, which uses Metal. Run later commands as `uv run vaultspec-rag` from the project root. To keep both out of the published dependencies, add them with `uv add --dev` and pass `--torch-group dev` to the repository setup ([install options]()). ### Prebuilt binaries Release archives for Windows x86-64, Linux x86-64 and ARM64, and Apple silicon carry both commands and need no Python toolchain. Install them with Scoop (`scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap`, then `scoop install vaultspec-rag`) or Homebrew (`brew tap nevenincs/tap https://github.com/nevenincs/homebrew-tap`, then `brew install vaultspec-rag`), or download one with its `SHA256SUMS` from the [releases page]() and compare the digest before extracting. On first launch a binary installs PyTorch, so it needs network access. The Linux archives need glibc 2.39 (Ubuntu 24.04, Debian 13, Fedora 40 or later); on older distributions use the standalone tool, which needs glibc 2.28. ### Set up each repository Run the repository setup once in the root of every repository you want to search. The command is named `install`, but it configures the repository; it doesn’t install the package. For a standalone tool or a binary: **Command** ```sh vaultspec-rag install --no-torch-config ``` For a project dependency, run the setup through the project. With the CUDA source from [install as a project dependency]() already in `pyproject.toml`, its PyTorch step has nothing to change. If the source is missing, the setup asks to add it: answer `y`, or pass `--yes` when nobody is there to answer; on Windows, declining leaves CPU-only PyTorch. Then sync, so anything it added takes effect: **Command** ```sh uv run vaultspec-rag install uv sync ``` The setup adds the agent integration (a rule, a skill, and the MCP entry) and creates `.vault/` if missing. In a host environment with a usable accelerator, it also provisions the models and Qdrant server. If the accelerator is not ready, those downloads are skipped with a reason; host `server start` provisions missing files before starting the service. Later repositories reuse the cache. Clients skip all dependency provisioning. - `--no-mcp` sets up terminal use without an agent. - `--local-only` keeps the index on disk instead of in the managed Qdrant server and skips its download. It changes storage only; the models still run on the GPU. The choice covers the whole service. A host setup saves this choice for later `server start` calls; a client cannot change the host’s saved backend. Run the service under the `embedded-local` profile, because the default profile refuses this backend. A startup flag overrides the environment, which overrides the saved choice. See [storage backends](). - `--mode` corrects how the setup detected the installation; see [what your agent launches](). ### Machine-readable output `install --json` and `uninstall --json` print one line in the shared envelope `{"schema", "status", "data"}`. `status` is one of `created`, `updated`, `unchanged`, `removed`, `skipped`, or `failed`. The exit code is `0` on success, `1` on failure, and `2` when the run completed but skipped a step that needed consent, such as the PyTorch patch nobody approved. A tool environment that needs the CUDA repair, run without authority to apply it, is a failure. The [command reference]() lists every flag and exit code. ### Start and verify From the host installation: **Command** ```sh vaultspec-rag server start vaultspec-rag --version vaultspec-rag server doctor ``` `server start` loads the models and waits until the service is ready. A healthy `server doctor` report shows PyTorch ready on a `cuda` or `mps` backend, every configured model cached, and the Qdrant binary present. The service doesn’t restart after a reboot; [running it automatically]() covers that. Then [index and run a first search](). ## Add a client to a Python project A client lets a uv-managed project list vaultspec-rag without GPU packages. It still needs a host installation on the same machine, running the service under your user account. Read the service’s release from the host installation: **Command** ```sh vaultspec-rag server status --verbose ``` From the project root, pin the client to the `Service release:` it prints, then set up the project so the agent launches the MCP server from the project environment: **Command** ```sh uv add --dev "vaultspec-rag[mcp]==" uv run vaultspec-rag install --mode dev ``` For terminal use only, add plain `vaultspec-rag==` and pass `--no-mcp`. A client skips PyTorch and every download on its own. Checked on Windows: the setup printed `PyTorch configuration: not needed (this installation is a client)`, reported PyTorch, models, and Qdrant as skipped, and the project environment held no PyTorch. `uv run vaultspec-rag server doctor` then reports the service’s release as matching this client. Index and search with the usual commands prefixed with `uv run`; start, stop, and upgrade the service from the host installation. ## What your agent launches The setup writes the agent’s MCP entry for the installation it detected: | `--mode` | When | The agent runs | | --- | --- | --- | | `tool` | Standalone tool, binary, or no project dependency | `uvx --from vaultspec-rag[mcp] python -m vaultspec_rag.server` | | `dependency` | Runtime project dependency | `uv run --no-sync python -m vaultspec_rag.server` | | `dev` | Development-group dependency | `uv run --no-sync python -m vaultspec_rag.server` | Either form loads no models and forwards every call to the service. The `tool` entry names no release, and a server whose release differs from the service’s has its tool calls refused with `service_version_mismatch`. The project forms run without syncing, so run `uv sync` after changing the project’s dependencies. [MCP integration]() covers client configuration and the tools. ## Upgrade A client refuses a service from any other release, so upgrade the host installation and every client together. Package upgrades acquire new code; `install --upgrade` refreshes repository artifacts from the code you are running. 1. Close connected agent sessions and run `vaultspec-rag server stop`. 2. Upgrade the host: `uv tool upgrade vaultspec-rag` for a standalone tool, `uv sync --upgrade-package vaultspec-rag` for a project dependency, `scoop update vaultspec-rag` or `brew upgrade vaultspec-rag` for a binary. 3. Check the upgraded host’s `vaultspec-rag --version`, then pin each client project to that release with `uv add --dev "vaultspec-rag[mcp]=="`. 4. In each repository, run `vaultspec-rag install --upgrade` (with `uv run` for a project installation), repeating any `--local-only`, `--no-mcp`, or `--no-torch-config` you used. 5. Start the service once from the updated host installation with `vaultspec-rag server start`, supplying its environment settings, then run `vaultspec-rag server doctor`. A running service keeps the code and settings it started with until it restarts. Indexes created with the former SPLADE sparse model are incompatible with SPARSEUP. Rebuild every repository indexed with that model after starting the updated service: **Command** ```sh vaultspec-rag --target index --rebuild --type all ``` Wait for each rebuild to complete and [verify the index]() before searching. Neither `install --upgrade` nor automatic file watching migrates these vectors; a `full_reindex_required` result needs this explicit rebuild. A standalone tool installed without the two index options upgrades to CPU-only PyTorch; `server doctor` says so and names the repair below. ### Environment settings during setup and startup Set download, cache, model, and backend variables in the process environment before running `install` or `install --upgrade`, and supply matching settings to the host process that runs `server start`. A client shell’s settings do not change a service that is already running. RAG does not import settings with Core’s `--env` or `--env-file` flags, and it does not read Core’s `.vaultspec/.env` store. The workspace-root `.env` can supply only RAG’s TypeSafe key, from an eligible project environment. See [environment loading]() for that eligibility and when to restart the service. ## When something goes wrong - `vaultspec-rag` isn’t found: for a standalone tool, run `uv tool update-shell` and open a new terminal; for a project dependency, use `uv run vaultspec-rag`. - A default model download fails: check network access and the cache findings in [the provisioning reference](). Default models require no login. - `server start` says the installation is a client: start the service from the host installation. - Commands report that no service is running: start it from the host installation. - Commands refuse to run against the service and name two releases: move the older side to the newer release, as in [upgrade](). - `install` refuses to edit `pyproject.toml`: rerun with `--yes`, or with `--no-torch-config` to manage PyTorch yourself. The [service troubleshooting]() and [index verification]() pages cover the rest. To remove a repository’s setup, see [uninstall](). ### Pin the GPU build A standalone tool on Linux or Windows with missing or CPU-only PyTorch, or whose upgrade record lacks the CUDA source, is repaired in place. Apple silicon never needs this. **Command** ```sh vaultspec-rag server doctor vaultspec-rag install --yes --no-torch-config vaultspec-rag server stop vaultspec-rag server start ``` `server doctor` names the build and prints the two repair commands; `install --yes --no-torch-config` applies them and verifies the result. Nothing has to be stopped during the repair, but the service and any agent session running the MCP server keep their old PyTorch until they restart. Don’t force a reinstall with `uv tool install --force` while either still runs: it can leave the tool missing packages. ### Server start cannot find the Qdrant binary The managed service uses a pinned, verified Qdrant binary. It does not look for `qdrant` on `PATH` or in the current directory. Host setup and service startup provision the managed binary when needed; a client never does. ### A Qdrant on PATH is no longer used To supply your own binary, set both `VAULTSPEC_RAG_QDRANT_BINARY` (an absolute path to a regular file, not a link) and `VAULTSPEC_RAG_QDRANT_BINARY_SHA256` (its SHA-256 digest) in the process environment before setup or startup. Supplying only one, or an invalid path or digest, fails instead of falling back to another binary. See [provisioning]() for supported binaries, cache verification, and download troubleshooting.