vaultspec-rag

Run the background service

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

The command blocks below are written with the uv run prefix, and one full invocation in the prose is written bare. Subcommands named in prose without the program - server start and the like - carry no prefix either way and are not counted here. If you installed as a tool or as a binary, drop it and run vaultspec-rag bare; if you run it without installing, it becomes uvx --from "vaultspec-rag[gpu]" vaultspec-rag. Choose an install route sets out the four routes and which prefix each one needs.

Run vaultspec-rag as a long-lived background service to keep the models loaded and the managed server running. The first query pays the model-loading cost once, and every later query reuses the already-loaded models.

This guide assumes the workspace is already installed and provisioned. “Provisioned” means install has fetched the model files and the Qdrant binary. It also means the environment has a PyTorch build for CUDA or Metal Performance Shaders (MPS). If you haven’t done that, start with the installation guide.

For the choice between the managed server and the local-only store, see the backends guide. For the vocabulary used here, see the glossary.

Examples use the uv run prefix, which runs the command inside a project environment. If you installed vaultspec-rag as a standalone tool, drop the prefix and call vaultspec-rag directly; see the installation guide for lane selection.

Start the service

Run:

Command

uv run vaultspec-rag server start

The command starts the managed Qdrant server on loopback at http://127.0.0.1:8765 and warms the models. It then binds the service on port 8766, writes a status file, and polls until the service reports ready.

If you don’t want a managed server, run local-only instead:

Command

uv run vaultspec-rag server start --local-only

Start it from the project. The service runs in whatever Python environment launched it, which is why uv run is the documented form; see Which Python environment runs the service.

Other start flags control the port, automatic updates, update timing, and the managed server. The CLI reference carries the full list.

Confirm it is running

Command

uv run vaultspec-rag server status

On a service that has been up for a while, that reads, with the environment path shortened to its last three segments:

Captured output

Server: running
Requests: ready for requests
Busy: idle
Address: http://127.0.0.1:8766
Service env: main\.venv\Scripts\python.exe
Uptime: 13 hours 19 minutes
Queue: nothing waiting
Processed jobs: 259 finished, 0 active, 0 waiting, 1 failed
  Last failure: job 9ab3eb6b (timeout), 3 hours 58 minutes ago
  Review failures: vaultspec-rag server jobs --failed
Current job: none active
Next action:
  vaultspec-rag search "<query>" --type code --timeout 120

status shows whether the service is up, its address, uptime, queue, processed jobs, and a suggested next action. Its Service env: line names the Python environment running the service. A failure that has already been retired to the history, as above, does not stop the service being ready: the count is there so a failure cannot pass unseen, and the line below it names the command that shows what happened.

Its exit codes:

• 0 running

• 3 stopped

• 4 crashed, divergent, or degraded; the label beside it says which, and Troubleshooting branches on that

• 5 warming, meaning the daemon holds the machine lock and is loading models; retry shortly

“Divergent” means the status file disagrees with the live process, for example naming a process ID that is no longer alive. If status reports crashed or divergent, see Troubleshooting.

To check each dependency rather than the process, run:

Command

uv run vaultspec-rag server doctor

Captured output

Service readiness
Backend: server
Readiness: ready for requests
Live service:
  status: running (running)
  process: pid 57856 (alive)
  network: port 8766 (listening)
  heartbeat: 12s ago
  release: 0.4.21 (matches this client)
Installed dependencies: ready
  torch: ready - CUDA available on NVIDIA GeForce RTX 4080 SUPER
  models: ready - all 3 model repos present in the cache
  qdrant: ready - qdrant binary resolves from provisioned
Provisioning (vaultspec-rag):
  declared mode: tool
  install mode: mismatch - .mcp.json launch shape disagrees with the declared mode
  version floor: ok

That capture is a healthy service with one thing to fix, which is the useful case to see: every dependency reads ready, and the last section still reports a mismatch because the .mcp.json entry launches the server a different way than the recorded mode. Search keeps working throughout. Readiness and provisioning are separate questions, and only the first one decides whether a query returns.

The release: line reads (matches this client) above because it did. When it does not, the client refuses the request rather than answering it:

Captured output

Refusing to search against the running service.
This vaultspec-rag client is 0.4.22 but the running service is 0.4.21.
A daemon from another release drops request fields it does not know rather than
rejecting them, so the answer would be computed over a different candidate set
with nothing to show it.
Next actions:
  1. Restart the service: vaultspec-rag server stop, then vaultspec-rag server start
  2. Confirm the release:  vaultspec-rag server status

That happens after an upgrade that left an older daemon running, and the two next actions are the whole fix. The wrapping above is unwrapped from the terminal’s; nothing else is changed.

doctor reports PyTorch and accelerator readiness, the compute backend (cuda or mps), the models, and Qdrant. It separately names the storage backend (server or local-only) and states whether the service is ready for requests. If a dependency reports not ready, follow its detail line, which names either a provision step or an install step.

One failure has a detail line that cannot tell you what to do, because the fix is not an install or a provision step: a corrupt collection in the managed store stops the server from starting at all. server qdrant quarantine moves it aside so the server starts again, listing the store’s collections when you run it with no name and requiring --yes to move one. Nothing is deleted and the affected root re-indexes on its next use. To keep working while you investigate, server start --local-only skips the managed store entirely. The backends guide covers both.

Both accept --json, and status accepts --verbose. For every field and exit code, see the CLI reference.

Route commands at the service

When a service is running, search and index detect it and route through it. You don’t need --port:

Command

uv run vaultspec-rag search "retry backoff"
uv run vaultspec-rag index

To target a service on a specific port, pass --port N. To run a command in the current process when the service is unreachable, add --allow-fallback:

Command

uv run vaultspec-rag search "retry backoff" --port 8766
uv run vaultspec-rag search "retry backoff" --allow-fallback

Without --allow-fallback, an unreachable service fails with an error and a suggested fix. That keeps a stopped or stale service from quietly running searches in-process with a cold model load. See the search and index guide.

Observe activity

To see recent and in-flight indexing work:

Command

uv run vaultspec-rag server jobs

That prints once and exits, which is what you want in a script. Watching an index run instead wants the live view:

Command

uv run vaultspec-rag server jobs --watch

--watch opens the interactive jobs interface, with per-job controls and a refresh you can slow down or speed up with --interval. It is the command to reach for while a first index is running on a large tree, where the one-shot form tells you only what was true at the moment you asked.

To inspect recent service and Qdrant logs:

Command

uv run vaultspec-rag server logs

server logs prints separate [service] and [qdrant] sections rather than combining the two timelines. To inspect one source:

Command

uv run vaultspec-rag server logs --source service
uv run vaultspec-rag server logs --source qdrant

If the service has stopped or crashed, run server logs anyway. It reads retained logs from the status directory, and source selection, filters, limits, and JSON output work the same way.

Both commands accept --json.

Three job signals are worth knowing. A failed job carries a stable error_kind in --json and on GET /jobs, classified once by the service so every surface agrees, and the human feed renders the matching remediation. A running job whose progress hasn’t moved for five minutes is flagged stalled, so you never have to infer it. If the service process dies mid-job, the next startup restores what it was running as interrupted, with the last progress and who started it.

An index job that reused vectors from an already-indexed sibling worktree carries a reuse block describing what it avoided re-encoding. See reusing vectors across worktrees for the mechanism, and the CLI reference for the block’s fields.

Control one job

server jobs shows the feed. To act on a single job, address it by id with server job, which accepts a unique prefix in human output:

Command

uv run vaultspec-rag server job show <job-id>

Five more verbs act on one job:

• server job pause requests a cooperative pause.

• server job resume resumes a paused job through reconciliation.

• server job stop requests cancellation without disabling automatic updates.

• server job retry creates a linked retry for a retryable terminal job.

• server job delete removes one terminal job from retained history.

Pausing a single job differs from pausing the service: server pause holds everything at safe checkpoints, while server job pause affects only the job you name.

Pause and resume

To hold the running service at safe checkpoints without stopping it:

Command

uv run vaultspec-rag server pause
uv run vaultspec-rag server resume

Pause before maintenance that shouldn’t race with indexing. To observe whether the service is quiet and what capacity the device has, without authorizing any GPU work:

Command

uv run vaultspec-rag server preflight

Stop and restart the service

Command

uv run vaultspec-rag server stop

To restart, stop and start again. No single restart command exists.

Stopping is safe on both platforms, and the vector store recovers either way. The platforms differ in how the stop reaches the daemon.

On Unix, server stop sends SIGTERM, which drives the daemon’s own graceful shutdown. It removes the status file and stops the Qdrant child last, so the store stays reachable until the service is down. The stop escalates to SIGKILL if the drain window expires.

On Windows, the daemon runs detached from any console, so a separate process cannot deliver CTRL_BREAK to it. The stop degrades to a bounded force-kill. The daemon runs none of its own teardown, so the CLI reaps the managed Qdrant child and clears the discovery pointer itself. The result is abrupt but safe.

server stop --json emits one outcome envelope per exit path for scripting. Every termination writes a shutdown audit line naming the initiating process, so you can always answer who stopped the service. On Windows the CLI writes that line itself, because the force-killed daemon never runs its own shutdown record.

Running it automatically

vaultspec-rag ships no service-manager integration. No systemd unit, launchd agent, or Windows service ships with it, and server start installs none. To run the service at login or boot, wrap uv run vaultspec-rag server start in your own unit, and point it at the project directory so it inherits the right Python environment.

Keep the index fresh automatically

Automatic updates are on by default: the service watches your files and reindexes changes, so you rarely index by hand. Manage updates on a running service:

Command

uv run vaultspec-rag server updates status
uv run vaultspec-rag server updates start <project>
uv run vaultspec-rag server updates stop <project>
uv run vaultspec-rag server updates timing <project>

To re-time updates for a project, pass --update-delay-ms or --repeat-update-delay-s to server updates timing. A value of 0 on either delay means “no delay”, not “disabled”.

The single off switch is --no-updates at start time, or VAULTSPEC_RAG_WATCH_ENABLED=0. The legacy debounce and cooldown inputs remain compatibility mappings for the adaptive bounds. See the automatic convergence reference for policy keys, limits, controller states, and telemetry.

Manage projects

One service serves many projects. To list the loaded project slots:

Command

uv run vaultspec-rag server projects list

To unload one:

Command

uv run vaultspec-rag server projects unload <project>

The service evicts idle projects over time, so you don’t normally need to unload by hand. Unload when you want to free a slot right away.

Which Python environment runs the service

server start spawns the daemon using the interpreter of the environment you launched it from, and the daemon inherits that environment’s packages, including PyTorch. So the environment decides which accelerator the service can use.

To see which environment is running the service, read the Service env: line in server status.

Starting from an environment without a supported accelerator fails immediately. server start refuses if the environment has no torch, has no supported accelerator, or has MPS CPU fallback enabled. It names the interpreter and the reason rather than spawning a daemon that crashes during model load.

A globally installed CLI is a fine client but is not a suitable service launcher unless its tool receipt pins the CUDA wheel. The installation guide covers that pin, and the architecture overview covers why the accelerator is required at all.

HTTP monitoring routes

The running service exposes read-only HTTP routes on loopback:

• GET /health - service health. Ungated.

• GET /readiness - dependency readiness. Requires the service token.

• GET /logs and GET /logs/json - grouped service and Qdrant log lines. Require the service token.

• GET /jobs - indexing activity. Requires the service token.

• GET /metrics - Prometheus metrics. Requires the service token.

Token-gated routes take the service token as a bearer: Authorization: Bearer <service_token>. The token is in the status file at ~/.vaultspec-rag/service.json, and /health also returns it.

The token plus loopback binding is a monitoring gate, not an authentication boundary. Keep the service loopback-bound.

The Model Context Protocol (MCP) server is a separate stdio process, not mounted on this HTTP service. It delegates to these same routes over loopback. See the MCP guide.

Manage the Qdrant server

Use server qdrant install, server qdrant status, and server qdrant clean. The backends guide covers the workflow.

Storage maintenance

Once running, the service maintains its own storage. An hourly cycle reclaims namespaces whose source roots have gone, archives data-bearing ones first, and reports disk health. Each cycle appears in server jobs and the /metrics gauges.

For what qualifies as reclaimable, the grace windows, the archives, and manual pruning, see the storage maintenance guide.

Troubleshooting

Port already in use

Another process is bound there. Use one port consistently: pass --port N or set VAULTSPEC_RAG_PORT, so commands and the service agree.

Status reports crashed or divergent (exit 4)

Exit 4 covers two different faults, and the fix for one is the wrong move for the other. Read the label status printed beside it rather than the code alone.

crashed (port silent) or crashed (heartbeat stale), or a divergent status file. No daemon is serving. The status file disagrees with the live process - naming a process id that is no longer alive, for instance. Re-run server start to overwrite it cleanly, and if that does not clear it, delete the status file at ~/.vaultspec-rag/service.json and start again.

degraded, which reads as “a service (PID N) holds the machine singleton but has not published its address”. A daemon is alive and holding the lock; what is missing or unreadable is the pointer it should have published. Deleting the file does not help - the holder is the only writer of canonical discovery, so nothing you delete makes it publish - and starting a second daemon only loses the race for the lock. Run server reconcile and give it time to converge. If it exits without converging, the holder is wedged: stop it (server stop, and on a resistant process by its own PID, which the label names) and start again.

The service won’t stop

A stale process ID can keep server stop from completing. Kill the process by its ID, then remove the status file at ~/.vaultspec-rag/service.json.

The managed server can’t start

Server mode needs the Qdrant binary. Provision it with server qdrant install, or run local-only with server start --local-only.

server start says the environment cannot run the service

The Python environment you launched it from has no supported accelerator. On Linux or Windows, run vaultspec-rag install, then uv sync, to install the CUDA wheel. On Apple silicon, install the standard macOS PyTorch wheel and make sure PYTORCH_ENABLE_MPS_FALLBACK is unset or 0. The service never runs on the CPU. See Which Python environment runs the service.

The index seems stale

Check server updates status and server jobs before reindexing. Automatic updates may be catching up, or an update may be in flight. Don’t reindex by hand while updates are running: manual reindexing competes for the single-writer accelerator and Qdrant path.

Something else

Capture server doctor --json, server status --json, and server logs, then open an issue on the issue tracker. Those three outputs are what a maintainer needs to reproduce a service fault. The tracker takes questions as well as bug reports.

Where to go next

• Getting started walks through a first index and search.

• Installation answers how to install and provision the workspace.

• Backends answers how the managed server compares with the local-only store.

• Architecture answers how the service, the models, and the store fit together.

• Automation answers how automatic updates behave.

• Search and index answers how to search and index through the service.

• Storage maintenance answers how to survey and reclaim index storage.

• MCP integration answers how to reach the service from an AI assistant.

• CLI reference catalogues every command, flag, field, and exit code.