rust-rag

rust-rag is a local retrieval backend with an Axum HTTP API, SQLite/sqlite-vec storage, and an ONNX embedding pipeline.

Documentation

• Start Guide - Product overview and search workflow.
• MCP Setup - Agent integration and bridge configuration.
• API Spec - Machine-readable OpenAPI 3.1 spec for integrations.

Authentication

The web app now uses a server-side authorization-code flow against Zitadel. The browser never talks directly to the Rust API anymore; the Next.js server exchanges the code, stores a signed session cookie, and proxies authenticated requests upstream with an internal API key.

Frontend environment variables:

• APP_BASE_URL - public URL of the Next.js app, for example http://127.0.0.1:3000
• AUTH_SESSION_SECRET - shared secret used to sign the session cookie
• ZITADEL_ISSUER - Zitadel issuer URL
• ZITADEL_CLIENT_ID - Zitadel application client ID
• ZITADEL_CLIENT_SECRET - Zitadel application client secret
• ZITADEL_REDIRECT_URI - optional override for the callback URL. Default: ${APP_BASE_URL}/auth/callback
• ZITADEL_SCOPES - optional scopes. Default: openid profile email
• RAG_API_URL - Rust API base URL used by the Next.js proxy. Default: http://127.0.0.1:4001
• RAG_FRONTEND_API_KEY - shared key the Next.js proxy sends to the Rust API

Rust API environment variables:

• RAG_AUTH_ENABLED - optional explicit toggle. If omitted, auth is enabled automatically when any API key is configured
• RAG_FRONTEND_API_KEY - shared key accepted from the authenticated Next.js proxy
• RAG_API_KEYS - optional comma-separated direct access keys for MCP or external clients. Each entry can be name:value or just value

Direct API and MCP clients can authenticate with either x-api-key: <key> or Authorization: Bearer <key>.

Reranking is controlled independently from retrieval:

• RAG_RERANKER_ENABLED - optional cross-encoder model loading toggle. Defaults to false; set it to true only when the host has suitable acceleration and both reranker model paths are configured.
• RAG_RERANKER_DEFAULT - optional server default for requests that omit the rerank field. Defaults to false. Requests can still opt in with rerank: true when the reranker is loaded.
• RAG_RERANKER_MODEL_PATH / RAG_RERANKER_TOKENIZER_PATH - required when RAG_RERANKER_ENABLED=true.

HTTP server

Start the main API server with the existing environment variables described in src/config/mod.rs:

cargo run

The default bind address is http://127.0.0.1:4001.

Local helper targets are available in the Makefile:

make run

rust-rag supports the Model Context Protocol (MCP) via direct SSE transport: The server exposes an in-process MCP transport at /mcp. This allows direct connection from clients like Claude Code without a bridge process.

claude mcp add --transport http rust-rag https://your-rag-server.com/mcp \
  --header "Authorization: Bearer your-mcp-token"

See MCP Setup for detailed configuration and authentication (device login) instructions.

Container image

Build the server container image from the repo root:

make docker-build

Run it locally with the SQLite data directory mounted from the host:

make docker-run

The image bakes in the model assets from assets/ and persists the database under /app/data/rag.db.

Kubernetes

The server deployment manifest is in deploy/kubernetes/rust-rag.yaml. It includes:

• a ConfigMap for server environment variables
• a PersistentVolumeClaim for the SQLite database
• a single-replica Deployment with startup, readiness, and liveness probes
• a ClusterIP Service on port 4001

Apply or remove it with:

make k8s-apply
make k8s-delete

Before applying in a real cluster, set the image: field in the manifest to the registry image you actually publish.