Copy page 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

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

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

[[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

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

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

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

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

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

uv add --dev "vaultspec-rag[mcp]==<release>"
uv run vaultspec-rag install --mode dev

For terminal use only, add plain vaultspec-rag==<release> 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]==<release>".

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

vaultspec-rag --target <repository> 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

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.