vaultspec-rag

Installing vaultspec-rag

Copied from vaultspec-rag's own documentation, and read against the pages written here at commit fbb5f385. Nothing in it needed answering differently.

Before you copy these

Every command below is written bare, with no prefix, which is what the standalone and prebuilt-binary routes want. In a project, put uv run in front of vaultspec-rag; without installing, put uvx --from "vaultspec-rag[gpu]" there instead. Choose an install route sets out the four routes and which prefix each one needs.

What you need before you start

The accelerator requirements on this page apply to an environment that runs the resident inference service. A command-line client or MCP adapter can be installed without model packages or CUDA when a compatible vaultspec-rag HTTP service is already running on the same machine.

For inference, use an NVIDIA GPU with CUDA on Linux or Windows, or Apple silicon with MPS on macOS. CPU inference and AMD GPUs are unsupported.

Choose a service resource profile:

Profile	Total system RAM	Free index-store space	Free CUDA memory at startup
managed-service (default)	16 GiB	8 GiB	12 GiB
embedded-local	8 GiB	5 GiB	6 GiB

The CUDA figures are the default model-loading admission limits; they do not apply to Apple silicon. See GPU memory settings. Allow additional disk space for the model cache.

Use embedded-local for smaller corpora or a machine with 8 GiB of unified memory. This profile also supports the server. Set VAULTSPEC_RAG_INDEX_SUPPORT_PROFILE=embedded-local in the service startup environment; setting it only in the query client’s shell does not configure the service. Run vaultspec-rag status to check the active profile and corpus limits.

Ensure network access to the package index, model host, and search-server release downloads.

For a Python installation, install uv and use CPython 3.13 or 3.14. Alternatively, install without Python.

Confirm your GPU is visible

On Linux or Windows:

Command

nvidia-smi

If that lists your card and a driver version, the driver is loaded. On Apple silicon, macOS supplies the driver; no CUDA installation is needed. PyTorch must report MPS available.

vaultspec-rag refuses to start when neither CUDA nor MPS is available, and it refuses MPS when PYTORCH_ENABLE_MPS_FALLBACK enables processor execution. Neither platform falls back.

Choose an install route

Choose what this environment runs

The package has two independent extras. gpu installs the model stack used by the resident inference service. mcp installs the model-free MCP stdio adapter, which forwards tool calls to that service over loopback HTTP. There is no rag extra.

Environment role	Requirement	What it can run
Command-line client and service controls	vaultspec-rag	Client commands against an already-running compatible HTTP service; no local models
MCP client adapter	vaultspec-rag[mcp]	MCP stdio transport plus the base client; no local models
Inference-service host	vaultspec-rag[gpu]	Resident HTTP inference service, indexing, and search
Combined host	vaultspec-rag[gpu,mcp]	Inference service and an MCP adapter in the same environment

The service is loopback-only. These client lanes separate Python dependencies and GPU ownership between processes on one host; they are not a documented network deployment across machines. VAULTSPEC_RAG_QDRANT_URL may point at remote vector storage, but Qdrant does not run the dense encoder, sparse encoder, or reranker. The process hosting vaultspec-rag inference still needs [gpu] and a supported accelerator.

The vaultspec-rag install command has a broader default than the base package: it enrolls MCP, downloads all three models, prepares PyTorch, and provisions managed Qdrant. That default creates the normal combined local topology. To enroll a deliberately lightweight client workspace, install the base or [mcp] package and run:

Command

vaultspec-rag install --no-provision --no-torch-config

Add --no-mcp for a command-line-only workspace. An inference host must be prepared with the [gpu] extra and the normal provisioning flow before server start.

Run without installing a tool

From your project root, run:

Command

uvx --from "vaultspec-rag[gpu]" vaultspec-rag install

uvx uses a temporary environment, but this command configures your project. See project setup for options, then verify the install.

Adding it to a project

Use a project dependency when collaborators need to share the same version. From your project root, run:

Command

uv add "vaultspec-rag[gpu]"

Continue with Python installation to complete setup, then verify the install.

Installing it as a standalone tool

Use one tool installation across projects without adding a project dependency:

Command

uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]"

On Linux or Windows, check the GPU build before using it. uv tool install doesn’t pin a CUDA wheel.

From each project’s root, set up the project, then verify the install.

Installing a prebuilt binary

Follow Install without Python.

For client and service-control commands without inference in that environment, Python routes omit gpu. Use the base package for the CLI, or [mcp] when that environment also runs the MCP stdio adapter.

Install without Python

The release publishes x86-64 Windows, x86-64 and ARM64 Linux, and Apple silicon macOS archives. Intel Macs are not covered; use a Python route there. The accelerator requirement remains the same: CUDA on Windows and Linux, MPS on Apple silicon.

vaultspec-rag and vaultspec-search-mcp ship in one archive per target. The archive embeds CPython 3.13, so the host needs no Python installation. On first launch, the embedded application installs the RAG wheel and resolves its runtime dependencies.

Install with Scoop or Homebrew

The channels live in the account tap, nevenincs/homebrew-tap. Add that tap once, then install the product for your platform.

On Windows:

Command

scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap
scoop install vaultspec-rag

On Linux or Apple silicon macOS:

Command

brew tap nevenincs/tap https://github.com/nevenincs/homebrew-tap
brew install vaultspec-rag

Each channel pins one archive URL and SHA-256 digest for the selected target. Extraction places the stable vaultspec-rag and vaultspec-search-mcp commands on PATH; the channel does not download one archive per command.

Download an archive directly

Use the release asset for your operating system and architecture. Replace <version> with the release version, such as 0.4.28.

Platform	Release asset
Windows x86-64	vaultspec-rag-v<version>-x86_64-pc-windows-msvc.zip
Linux x86-64	vaultspec-rag-v<version>-x86_64-unknown-linux-gnu.tar.gz
Linux arm64	vaultspec-rag-v<version>-aarch64-unknown-linux-gnu.tar.gz

Open the release page and download the archive and SHA256SUMS from the same vaultspec-rag-v<version> release. The checksum file contains one line for each release asset. Match the line whose filename exactly matches your archive.

Verify the archive before extracting it:

Platform	Compute the archive digest	Find the matching release entry
Windows PowerShell	Get-FileHash -Algorithm SHA256 -LiteralPath .\<archive>	Select-String -Path .\SHA256SUMS -SimpleMatch <archive>
Linux	sha256sum <archive>	grep -F -- "  <archive>" SHA256SUMS

Compare the computed digest with the digest on the matching SHA256SUMS line. Do not extract or run the archive when they differ. Download both files again from the same release and repeat the check.

Extract the verified archive and run the stable command name:

Windows PowerShell:

Command

Expand-Archive -LiteralPath .\vaultspec-rag-v<version>-x86_64-pc-windows-msvc.zip `
  -DestinationPath .\vaultspec-rag
.\vaultspec-rag\vaultspec-rag.exe --version

Linux:

Command

mkdir -p vaultspec-rag
tar -xzf vaultspec-rag-v<version>-x86_64-unknown-linux-gnu.tar.gz -C vaultspec-rag
chmod +x vaultspec-rag/vaultspec-rag vaultspec-rag/vaultspec-search-mcp
./vaultspec-rag/vaultspec-rag --version

For an ARM64 Linux host, use the ARM64 asset from the table instead.

Inspect the archive layout

Every verified archive contains these members at its top level:

Member	Purpose
vaultspec-rag or vaultspec-rag.exe	Command-line client and service control
vaultspec-search-mcp or vaultspec-search-mcp.exe	MCP stdio adapter
LICENSE	Project licence
README.txt	Target and runtime notes
manifest.json	Machine-readable bundle metadata and member hashes

Open manifest.json after extraction to check schema, product and version, release tag, target, archive format, runtime, requirements, and platform metadata. Its files array records the role, size, and SHA-256 of each executable and release document. Confirm that archive.name matches the downloaded filename, target matches your host, and every files[].name exists with its listed size and digest. The manifest intentionally does not hash the enclosing archive. SHA256SUMS is the source of truth for that outer archive digest.

The manifest’s platform.glibc_floor records the Linux loader floor. Check which Linux binary your distribution can run before using a Linux archive.

First launch requirements for binaries

The binary bootstraps the same accelerated PyTorch build this project resolves. It uses a target-specific CUDA wheel pinned from the project lockfile, then resolves the remaining packages from their configured indexes.

First launch needs network access to the package indexes and enough disk space for the GPU wheel and CUDA runtime dependencies. It also needs an NVIDIA GPU with a working CUDA driver. The binary has no CPU mode.

The archive contains no model files or Qdrant server binary. Run vaultspec-rag install to prepare the normal local topology; that step downloads models and provisions Qdrant. Those downloads also require network access and additional disk space. A successful vaultspec-rag --version check confirms the bootstrap completed, not that model provisioning is complete.

Nothing in Install with Python applies to the archive route. Go to Verify the install.

Install with Python

For project dependencies, prefix vaultspec-rag commands with uv run. For standalone tools, run vaultspec-rag directly. For temporary environments, use the uvx invocation.

Set up a project

By default, installation sets up coding-agent integration, including Model Context Protocol (MCP), downloads model files into the cache, and provisions a checksum-verified Qdrant binary.

This is provisioning for an inference host, regardless of which extras are already in the current environment. A base or [mcp] install stays lightweight only when setup is also run with --no-provision; package extras and installer provisioning are separate choices.

For CLI-only use, add --no-mcp. To use an embedded store, add --local-only; see storage backends for its requirements.

If your project needs a PyTorch configuration patch, the installer asks before adding a Linux/Windows CUDA package source to pyproject.toml. Its platform marker keeps that source inactive on macOS. Enter y to accept, or add --yes for unattended installation. Use --no-torch-config to skip that configuration step.

From your project root, run:

Command

vaultspec-rag install

See the install command reference for all flags and exit codes. For project dependencies, complete the install with a sync. Then verify the install.

Choose where vaultspec-rag lives

Project and standalone tool routes.

install records where vaultspec-rag sits in your workspace. That placement decides how vaultspec-rag launches its Model Context Protocol (MCP) server, which exposes search to AI assistants. See MCP integration for the server itself.

Command

vaultspec-rag install --mode tool

• tool launches the server through an ephemeral uvx invocation, independent of any project environment. This is the default when your project doesn’t depend on vaultspec-rag.

• dependency launches it through uv run inside the project environment. A runtime dependency ships with your project’s published distribution.

• dev launches identically to dependency but records the placement as development-only, so it doesn’t ship.

With no --mode, install detects the placement from pyproject.toml: a runtime dependency resolves to dependency, a default dev-group entry to dev, anything else to tool. It refuses an explicit --mode dependency or --mode dev when no pyproject.toml exists to declare against, rather than guessing.

install commits the choice to .vaultspec/workspace.json, per package, so a workspace holding both vaultspec-rag and vaultspec-core keeps each placement without one overwriting the other. Placement is independent of --local-only: placement decides where the tool lives, the backend flag decides where the index is stored.

Complete the install with a sync

Project dependencies only.

After accepting the PyTorch configuration, resolve the project’s dependencies:

Command

uv sync

To fold this into the install step, pass install --sync, which runs uv sync --reinstall-package torch after the config step.

Pin the GPU build

Use these steps to repair missing or CPU-only PyTorch in a GPU-enabled uv tool installation on Linux or Windows. Apple silicon uses the standard wheel’s MPS support; follow Verify the install.

A pin saves the direct torch wheel URL in the tool’s installation receipt through --with. Unpinned upgrades can select a CPU build. Project pyproject.toml settings and uv sync don’t configure tool environments.

If ModuleNotFoundError prevents vaultspec-rag from running, see failed reinstall recovery before attempting these steps.

1. If vaultspec-rag runs, preview the repair:

   Command

   vaultspec-rag install --dry-run --no-torch-config
   

   For a diagnosed missing or CPU-only CUDA build, this prints a pinned, platform-specific uv tool install command. Save it. The preview neither replaces the tool nor checks for processes holding its files. If no command appears, follow the diagnosis and verification instructions.

2. Before running the saved command, locate the tool environment and stop its service:

   Command

   uv tool list --show-paths --show-python --show-with
   vaultspec-rag server stop
   

   Resolve any stop failure before continuing. Close MCP client sessions using the tool. Move shells and editors outside its environment directory. Open file handles can leave an incomplete installation on Windows.

3. Run the saved command from a shell outside the tool environment. Preserve its --python selection and wheel URL; Python must match the wheel’s compatibility tags.

4. Run the tool listing again. Confirm it shows the direct torch URL, then verify the install.

For unresolved verification failures, report the failed command with the error, tool listing, OS, and Python version.

Verify the install

Check the version:

Command

vaultspec-rag --version

This reports vaultspec-rag v0.4.32. Run the readiness report, which checks PyTorch and the resolved GPU backend, the model cache, and the Qdrant binary and server:

Command

vaultspec-rag server doctor

Check Readiness and the status of each dependency. To interpret the report and check index coverage, follow verify the index.

When something goes wrong

GPU backend unavailable

A torch: not ready result from server doctor can mean missing PyTorch, an unavailable accelerator, an unsuitable PyTorch build, or rejected MPS fallback. Read the diagnostic detail before choosing a repair.

First, confirm your GPU is visible. If that check fails, resolve the visibility problem before repairing packages. Apple silicon uses MPS, not CUDA.

For a project dependency, follow Python installation, including dependency sync. For a standalone uv tool on Linux or Windows, follow GPU build pinning. Running uv sync in a project doesn’t update the tool’s environment.

After making changes, verify the install.

install refused to repair the tool environment

The installer prints a repair command instead of replacing the environment it is running in. Follow GPU build pinning to stop clients and run the saved command from outside the tool environment. See install options for configuration flags.

A tool environment is missing packages after a failed reinstall

An interrupted reinstall can leave vaultspec-rag unable to run, reporting ModuleNotFoundError. It cannot generate a repair command in this state.

Report the failed command with the error, OS, Python version, and output of uv tool list --show-paths --show-python --show-with. Include any saved pinned install command. Do not force another reinstall while the service or clients still use the tool environment; the repair procedure requires them to stop first.

install refused to edit pyproject.toml

It needs consent it doesn’t have, and exits non-zero. Re-run with --yes to approve, or --no-torch-config to manage PyTorch yourself.

server start cannot find the Qdrant binary

Install the Qdrant binary, then retry your original start command. For a project dependency, add uv run:

Command

vaultspec-rag server qdrant install

To use embedded storage instead, follow storage backends.

The Qdrant download failed a checksum

The archive didn’t match the committed digest, and the command deleted the partial file. Retry. On an air-gapped host, register your own executable with server qdrant install --binary PATH.

For anything not covered here, the issue tracker takes questions as well as bug reports. It’s the only support channel.

The model cache and its first download

Model files use the Hugging Face cache. Set HF_HOME to a persistent location before setup if you need to choose where downloads are stored.

The default sparse model, naver/splade-v3, is gated. Before the default provisioning flow, sign in to Hugging Face, open the model page, and accept its access conditions. Then authenticate the account that runs the service with either HF_TOKEN or a persisted login:

Command

hf auth login

HF_TOKEN takes precedence over the token stored by the login command. A token alone is not sufficient until its account has accepted the model conditions. Without both access approval and authentication, model download or server start may report a 401, 403, GatedRepoError, or “repository not found”; for a gated public model, those messages can mean missing authorization rather than a nonexistent repository.

The model is licensed under CC-BY-NC-SA-4.0, which restricts commercial use and adds attribution and share-alike obligations. Confirm that the license fits your use before enabling the default sparse lane.

If that license or gate is unsuitable, set VAULTSPEC_RAG_SPARSE_ENABLED=0 in the inference service environment. This disables SPLADE and produces dense-only indexes and searches; lexical/sparse matching and hybrid fusion are absent. Apply the setting consistently to every service process and rebuild existing indexes so stored vector schemas match. Dense embedding and reranking still run locally, so disabling sparse does not remove the [gpu] or accelerator requirement.

The install model-prefetch step, server warmup, and the server doctor cache check all honour the toggle: with VAULTSPEC_RAG_SPARSE_ENABLED=0 they never provision, warm, or probe the gated SPLADE repository, so a dense-only install never needs Hugging Face access or authentication for it. See model selection and toggles for the canonical settings reference.

If a run exhausts GPU memory, that’s a runtime concern rather than an install one: see tuning for memory and speed. On MPS, memory is unified with the rest of the system rather than dedicated.

Upgrade

Close connected clients before stopping the service. The service may be shared with other clients, so coordinate the interruption.

The service and setup commands use vaultspec-rag. For project dependencies, add uv run; for the temporary route, use your original uvx invocation. See Python installation.

Command

vaultspec-rag server stop

Resolve any stop failure before updating. Use the command for your installation route:

Installation route	Update command
Project dependency	uv sync --upgrade-package vaultspec-rag
Standalone tool	uv tool upgrade vaultspec-rag
Scoop	scoop update vaultspec-rag
Homebrew	brew upgrade vaultspec-rag

uv upgrades respect version constraints. Preserve your Python selection and CUDA build pin.

For uvx, follow version selection and keep your chosen extras.

From each project root, refresh the bundled rules, skills, and MCP files. Reuse your original installation options, including --no-mcp or --local-only if you selected them:

Command

vaultspec-rag install --upgrade

If the release notes specify a new bundled Qdrant version, update Qdrant:

Command

vaultspec-rag server qdrant install --upgrade

Restart the service with its usual options:

Command

vaultspec-rag server start

Reconnect clients and verify the install. If the release requires rebuilding indexes, follow reindexing.

Remove it

Uninstalling removes the project’s integration, not the package. It preserves data by default. Read the uninstall flags before choosing data removal.

If RAG is a project dependency, prefix vaultspec-rag commands with uv run.

1. From your project root, preview the integration changes:

   Command

   vaultspec-rag uninstall
   

2. Review the preview, then apply it:

   Command

   vaultspec-rag uninstall --force
   

3. For optional shared-index cleanup, inspect the store and follow storage maintenance. Models and Qdrant binaries are shared across projects; removing one project’s setup does not require deleting them.

4. Before removing the package, run vaultspec-rag server stop and close connected MCP clients. Stopping the service affects its other clients too.

5. Remove the package using your installation method:

   Installation	Command
   uv project dependency	uv remove vaultspec-rag
   uv tool	uv tool uninstall vaultspec-rag
   Scoop	scoop uninstall vaultspec-rag
   Homebrew	brew uninstall vaultspec-rag

Which Linux binary your distribution can run

A binary links against whatever C library built it, so a download labelled only “Linux” may not run on your distribution.

Binary	Requires	Covers
x86_64-unknown-linux-gnu	glibc 2.28	Debian 10+, Ubuntu 20.04+, RHEL 8+, Amazon Linux 2023
aarch64-unknown-linux-gnu	glibc 2.28	Debian 10+, Ubuntu 20.04+, RHEL 8+, Amazon Linux 2023

Check yours with ldd --version. On an older distribution the binary doesn’t start, and the error names a missing symbol version rather than saying the distribution is too old.

Every currently offered download meets the 2.28 floor.

Installing from the package index has no such floor and works wherever the Python and GPU requirements are met.

Where to go next

• Getting started walks through your first index and search.

• Search and index answers how ranking works and what the filters do.

• Backends answers when to choose the on-disk store over the managed server.

• Configuration answers which environment variables and settings exist.

• Project overview answers what vaultspec-rag is, if you’re still deciding.