vaultspec-rag

Storage backends

Copied from vaultspec-rag's own documentation, and read against the pages written here at commit 04610a5c. 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.

Examples use the installed-tool form and call vaultspec-rag directly. If vaultspec-rag is a project dependency, prefix each command with uv run; see the installation guide for lane selection, including the standalone tool and no-install routes.

Choose a backend

vaultspec-rag uses a managed local Qdrant server by default. Choose local-only storage if you cannot run a separate Qdrant process.

	Managed Qdrant (default)	Local-only
Process	Separate, supervised Qdrant process	Embedded store
Default index location	~/.vaultspec-rag/qdrant-server/storage	.vault/data/search-data/qdrant/
Qdrant binary	Pinned and checksum-verified	No binary download

Managed storage separates projects by namespaces based on each project’s resolved root. Local-only storage keeps the index inside each project.

Both backends need the GPU runtime and models. Local-only storage avoids the Qdrant binary download; packages and models still need downloading if they are not cached.

Change the backend

Switching backends does not transfer indexes. To keep an existing index, follow index migration. Otherwise, build an index after switching.

If the service is running, stop it first. This interrupts all connected clients. Starting an already-running service does not change its backend.

Command

vaultspec-rag server stop

Wait for the stop to succeed, then choose one of the following starts.

Use a local-only index

Command

vaultspec-rag server start --local-only

Include --local-only on every start. A plain server start overrides a saved or environment-based local-only selection, including one saved by install --local-only.

Use managed Qdrant

Command

vaultspec-rag server start --qdrant

The explicit flag re-enables managed Qdrant if it was disabled. If the binary is missing, follow the install command printed by startup. See startup options for automatic provisioning.

After either start, build or refresh the project’s index.

Check the service

Command

vaultspec-rag server status

Check that the service is running. For managed Qdrant, also check its process and connection:

Command

vaultspec-rag server qdrant status

server doctor assesses the invoking process’s backend configuration alongside service health; its backend label does not prove which backend the running daemon uses.

For startup failures, follow service troubleshooting. For collection recovery or disk cleanup, use storage maintenance.