OpenRouter Setup

OpenRouter is the AI provider that VaultRAG uses to connect to models from OpenAI, Anthropic, Google, and more. This walkthrough covers how to create an account, configure your privacy settings, add credits, and generate an API key.

Step 1: Sign Up

Go to openrouter.ai and click the Sign Up button in the top right corner.

Step 2: Open Settings

Click the settings icon to open your account settings. This is where you will configure your privacy preferences.

Step 3: Configure Guardrails

Navigate to Settings > Guardrails. Under Privacy Settings, you will see four toggles that control how your data is used for training and logging purposes:

• Enable paid endpoints that may train on inputs: Controls whether paid endpoints can anonymously use your data for training purposes. We recommend turning this off.
• Enable free endpoints that may train on inputs: Free model providers often retain and/or train on prompts and completions. We recommend turning this off.
• Enable free endpoints that may publish prompts: Allows free model providers to publish your prompts and completions to public datasets. We recommend turning this off.
• ZDR Endpoints Only: When enabled, you will only be able to route to endpoints that have a Zero Data Retention policy. We recommend turning this on for maximum privacy.

For the best privacy, disable the first three toggles and enable ZDR Endpoints Only.

Step 4: Add Credits

Navigate to the Credits section to add funds to your account. OpenRouter uses a pay-as-you-go model where you only pay for the tokens you use. A small amount like $5 or $10 is enough to get started and will last a while for typical usage.

Step 5: Navigate to API Keys

Go to the Keys section from the sidebar or account menu. This is where you will create the API key that VaultRAG needs to connect to OpenRouter.

Step 6: Create an API Key

Click Create Key to generate a new API key. Give it a name like "VaultRAG" so you can identify it later.

Step 7: Copy Your Key

Your new API key will be displayed. Copy it immediately as it will only be shown once. Keep it somewhere safe so you can paste it during the VaultRAG setup process.

Getting Started

VaultRAG is a desktop application for managing and querying your files using retrieval-augmented generation. Connect to leading AI models, index your documents, and get grounded answers with citations.

When you first launch VaultRAG, a setup wizard will walk you through the initial configuration. This guide explains each step.

Step 1: License Activation

The first time you open VaultRAG, you will be prompted to enter your license key. This is the key you received by email after your purchase, in the format VR-XXXX-XXXX-XXXX-XXXX.

Paste your license key into the field and click Activate. Your license allows activation on up to two devices.

Step 2: Choose Your Vault Folder

Your vault folder is the directory that VaultRAG will monitor and index. Any files you place inside this folder will be read and processed by AI so you can search and ask questions about them.

We recommend creating a new, dedicated folder for your vault (for example, Documents/VaultRAG). This is not strictly required — you can point VaultRAG at an existing folder — but a dedicated folder gives you clear control over what gets indexed.

Important: All files in your vault folder will be indexed and read by AI models. Do not place sensitive personal information (tax documents, passwords, medical records, etc.) in this folder unless you are comfortable with that data being sent to your configured AI provider.

You can click Browse... to select a folder, or type a path directly. This can be changed later in Settings.

Step 3: Connect Your AI Provider

VaultRAG requires an AI provider to power its chat, search, and indexing features. An AI provider API key is required to use the AI features of this application. Without one, you will not be able to chat with your documents, generate embeddings, or run searches.

Currently, VaultRAG supports OpenRouter as a provider. OpenRouter gives you access to hundreds of models from providers like Anthropic, OpenAI, Google, and more through a single API key.

Getting an OpenRouter API key

If you don't have an OpenRouter account yet, see the OpenRouter Setup section of this guide. If you already have a key, paste it into the API key field.

Testing the connection

After entering your API key, click Test Connection to verify that VaultRAG can reach OpenRouter with your credentials. Once the connection succeeds, click Load Models to fetch the list of available models. This will populate the model selection dropdowns in the next part of this step.

Step 3 (continued): Model Selection

After loading models, you will see three model selection fields:

Chat model

This is the main model used when you ask questions about your documents. Pick a model that balances quality and cost for your needs. We recommend anthropic/claude-sonnet-4.6 for chat, but you can choose any model available through your provider.

Note: only certain models can read images. If you need the chat to parse screenshots, photos, or diagrams in your vault, use a vision-capable model like anthropic/claude-sonnet-4.6 or google/gemini-2.5-pro.

Embedding model

The embedding model converts your documents into vector representations used for search and retrieval. This runs when your files are indexed and when you ask a question. We recommend perplexity/pplx-embed-v1-0.6b. On OpenRouter, sort or filter models by throughput (TPS) and pick a fast one for this slot since every indexed file passes through it.

Key phrase model

This model extracts key phrases from your documents to improve search accuracy. We recommend inception/mercury-2. As with the embedding model, this one runs across your whole vault during indexing, so search OpenRouter for models with high TPS to keep indexing fast.

All model selections can be changed later in Settings.

Step 4: Global Hotkey

VaultRAG can be opened from anywhere on your computer using a global keyboard shortcut. The default is Cmd+Shift+Space on Mac. Click the field and press your preferred key combination to change it.

This lets you quickly pull up VaultRAG to ask a question without switching windows or finding the app in your dock.

macOS permissions

On macOS, global hotkeys require Accessibility permissions. If the hotkey does not work after setup, go to System Settings > Privacy & Security > Accessibility and make sure VaultRAG is listed and enabled. You may need to click the lock icon and add VaultRAG manually if it does not appear.

Troubleshooting

If you previously installed VaultRAG, you may need to remove it from the Accessibility list and add it again. Open System Settings > Privacy & Security > Accessibility, select VaultRAG, click the minus button to remove it, then click the plus button to add it back. You must restart VaultRAG after making these changes for them to take effect.

Step 5: Web Search (Optional)

VaultRAG can optionally search the web during chat using Tavily, a search API built for AI applications. When enabled, you can toggle web search on or off in the chat interface to supplement your vault documents with live web results.

This step is entirely optional. If you do not need web search, leave the field blank and click Next. You can always add a Tavily key later in Settings.

Getting a Tavily API Key

To enable web search, you need a free API key from Tavily. Follow these steps:

1. Visit Tavily

Go to tavily.com. Tavily is a search API designed specifically for AI applications, providing clean, structured results optimized for LLM consumption.

2. Create an Account

Click the small Sign Up link underneath the Continue button to create a free account.

3. Create an API Key

After signing in, you will be taken to the Tavily dashboard. Click the + button to the right of API Keys to create a new API key. The free tier includes 1,000 API calls per month, which is more than enough for typical use.

4. Name Your API Key

Give your API key a name. Any name is fine.

5. Copy Your API Key

Click the copy button next to your API key to copy it to your clipboard.

Once you have your API key, paste it into the Tavily field in VaultRAG and you are all set. You can test the connection in Settings > AI at any time.

Step 6: Finishing Up

The final step confirms that setup is complete and gives you a few tips to get started:

• Type help in the main window to see available commands and shortcuts.
• Use the Settings menu to update your providers, API keys, models, and vault location at any time.
• Only files inside your vault folder are indexed for search.

Click Finish to close the setup wizard and start using VaultRAG. All of these settings can be changed later from the Settings menu inside the app.

Enable macOS permissions for the launch shortcut

On macOS, VaultRAG asks for Accessibility and Input Monitoring permissions so the global launch shortcut can bring VaultRAG to the front from any app. Most in-app shortcuts work without these permissions, but the global launch shortcut needs them to listen for your key combination while another app is active.

When macOS shows the permission prompt, click Open System Settings. In Privacy & Security > Accessibility, turn on VaultRAG. macOS may ask for your password or Touch ID to confirm the change.

If the launch shortcut still does not bring VaultRAG to the front, also open Privacy & Security > Input Monitoring and enable VaultRAG there as well, then restart the app.

Once setup is complete, you can navigate VaultRAG using simple text commands. Type help in the chat to show the help guide with all available commands and keyboard shortcuts. Type vault to open the vault browser, or press Tab to switch between Chat, Vault, and Analytics views. Type analytics to view your usage statistics, or type settings to open the settings panel.

Settings

The Settings panel lets you adjust VaultRAG's configuration at any time. Open it from the menu inside the app. Settings are organized across five tabs: General, AI, Indexing, Files, and About.

General

The General tab covers your vault location, global hotkey, appearance, database maintenance, and vault statistics.

Vault Path

The root folder that VaultRAG indexes and searches. Every file inside this folder (and all of its subfolders) becomes part of your vault and is made searchable by name, content, and AI-generated embeddings. Click Browse... to select a new directory or type a path directly. When you change the vault location, the index will be rebuilt automatically against the new folder.

Recommended: create a dedicated folder just for VaultRAG, for example ~/VaultRAG on macOS/Linux or C:\Users\<you>\VaultRAG on Windows, and point the vault path at that folder. Move or copy in only the documents you actually want indexed. This keeps the vault focused, makes indexing faster, and gives you a clean spot to back up or sync.

You can set the vault path to a broad location like your home directory, Documents folder, or an entire drive, but it is not recommended. VaultRAG will try to index everything it can reach underneath that path, including application data, caches, downloads, and other files you probably do not want to search. The result is a much larger index, slower scans and embedding runs, higher disk and memory use, and noisier search results.

Warning: Avoid pointing the vault at system folders (such as /, /System, C:\Windows, Program Files, or hidden config directories like ~/Library or AppData). Use a folder you own and control, and ideally one you can back up on its own.

Global Hotkey

Launches VaultRAG from anywhere on your system. Click the field and press your preferred key combination to change it. On macOS, you need to grant VaultRAG permission under System Settings > Privacy & Security > Accessibility and Input Monitoring for the hotkey to work. Restart the app after changing these permissions.

Window Controls

Use the Show window control buttons (close, hide, fullscreen) checkbox to toggle the platform-native window buttons in the title bar. When enabled, macOS shows the standard traffic-light buttons and Windows shows its standard minimize, maximize, and close controls. When disabled, VaultRAG hides them for a cleaner, more minimal title bar; you can still close or move the window using your operating system's normal shortcuts and gestures. The change takes effect immediately.

Appearance

Choose from over 20 built-in themes including Dark, Light, Catppuccin, Dracula, Nord, Tokyo Night, GitHub, and more. The change takes effect immediately.

Database Maintenance

Three tools to manage the vault's internal database:

• Verify checks for discrepancies between files on disk and the vault database without making changes.
• Repair syncs the database with the current state of files on disk, adding missing files and removing deleted entries while preserving existing AI-generated data.
• Rebuild performs a full clean and rebuilds the database from scratch.

Warning: Rebuild erases all AI-generated data including embeddings, summaries, and relationships. Only use it if Repair does not resolve the issue or you want a fresh start.

Vault Statistics

A snapshot of your vault showing embedding cache size, document count, categories, indexed folders, relationships, graph database size, and embedding dimensions. Click Refresh to update after making changes.

AI

The AI tab configures web search powered by Tavily.

Web Search (Tavily)

Enable web search to allow the AI to search the internet for current information during chat. Get a free API key at tavily.com (1,000 searches/month free). Paste your key and click Test Tavily to verify the connection.

Search Depth

Choose between basic (faster) and advanced (deeper crawling for more thorough results).

Max Results

The number of web results to return per search (1-20).

Indexing

The Indexing tab controls how VaultRAG generates summaries and manages the prompts used for AI processing.

Summary Settings

Configure the maximum number of characters extracted from a document for summary generation. Larger values give the model more context but use more tokens. You can also toggle Automatically Generate Summary When Adding Files to have summaries created as soon as files are added to the vault.

System Prompts

Customize the system prompt that guides how the AI responds during chat. You can create multiple prompts for different use cases and switch between them.

Summary Prompts

Customize the prompt used when generating document summaries. This controls what the AI focuses on when summarizing your files.

Files

The Files tab controls how files are handled when added to the vault and lets you define ignore rules and custom file type mappings.

Add Behavior

Toggle whether files are moved into the vault folder when added, or left in their original location.

File Ignore Rules

Define patterns to exclude files from being indexed. Each rule has a pattern and a match type: Starts With, Ends With, Contains, or Equals. Use this to skip temporary files, lock files, or anything else you do not want indexed.

File Type Mappings

Map custom file extensions to a parser so VaultRAG knows how to read them. Enter a file extension and select a parser to handle it. This is useful for non-standard file types that contain text content you want searchable.

About

The About tab shows the current version of VaultRAG and provides access to the EULA, update checks, and troubleshooting tools.

EULA

View the End User License Agreement and notices.

Check for Updates

Click to check whether a newer version of VaultRAG is available.

Troubleshooting

Open the log folder to access diagnostic logs. Useful if you need to report an issue or debug unexpected behavior.

Chat

The chat interface is where you ask questions, search your vault, and interact with AI. Results from your vault and the web are displayed inline alongside the AI's response.

Vault Search Results

When you ask a question, VaultRAG searches your indexed documents and returns relevant matches under In Your Vault. Each result shows the document name, match score, and a link to open the file.

Web Search Results

If web search is enabled, the AI can also pull in live results from the internet. These appear under Best Books Available (Web Results) or similar headings depending on your query, giving you both local and online sources in one response.

Pinned Documents

Pin documents to the right sidebar so they stay accessible across your conversation. Pinned documents remain in context as you ask follow-up questions, making it easy to work through a set of files throughout the day.

Context Panel

The context section on the right shows documents currently loaded into the conversation. This gives you visibility into exactly what the AI is referencing when it answers your questions.

Chat Input

The input bar at the bottom includes controls for toggling web search, attaching files, viewing conversation history, selecting your AI model, and starting a new conversation.

Vault

The vault is your file manager inside VaultRAG. Browse folders, import documents, and generate AI summaries without leaving the app.

Importing Files 1

The highlighted import buttons (1) open a picker for adding files or whole folders into the current vault location. You do not have to use them though - the vault accepts files however you normally move them around your computer:

• Copy and paste with Cmd+C / Cmd+V (or Ctrl on Windows) from Finder, Explorer, or another vault folder.
• Right-click in the grid for a context menu with paste, new folder, and other actions.
• Drag and drop files or folders straight into the grid from any other application, or drag them out of the vault into another location.

Generate Summaries 2 3

The highlighted toolbar button (2) fills in missing AI summaries across the entire vault. If summary generation on import is enabled in Settings, newly imported files are summarized automatically, so most users only need this button when summaries were skipped, disabled, or missing. Summaries power semantic search and make the detail panel more informative.

For a single file, select it and use the Summary panel on the right (3). Click Generate to create a summary for just that file. You can also edit the summary text by hand and click Save to keep your own wording, or Clear to remove the summary entirely. Saved summaries are stored per file and used by search and chat.

Folder Sidebar

The left sidebar shows your folder hierarchy with pinned folders at the top for quick access. The Drives section lists mounted volumes so you can browse outside the vault root when you need to.

Document Details

Select a file to open the detail panel on the right. It shows the file type, size, modified and created dates, full path (with a copy button), and the AI-generated summary. The Actions group at the bottom lets you Open the file in its native application, Show in Finder, or Delete it.

Toolbar

The toolbar across the top of the vault holds navigation, view, and action controls. From left to right: back, forward, up, and home for moving through the folder tree; breadcrumbs showing your current path; a sort menu; grid, list, and column view toggles; an info-panel toggle; refresh; a hide-indexed filter; and the import and tag controls covered above. The search box on the right searches filenames and indexed content across the current folder.

You can also customize the toolbar. Use the toolbar options menu to hide buttons you do not use, add them back later, show all toolbar items, hide optional buttons, or reset the toolbar to its default layout. If you prefer the window controls in the toolbar, turn on Show Window Controls in Toolbar. The same window-control setting is also available from Settings.

Analytics

The Analytics dashboard tracks your AI usage so you always know what you are spending. Open it from the menu inside the app.

Today and This Month

Summary cards at the top show request counts, token usage, and cost for today and the current month at a glance.

Usage Over Time

A chart showing daily token usage and cost over a configurable time range (7 days, 30 days, etc.) so you can spot trends in your spending.

Usage by Model

A breakdown of every model you have used this month, showing request count, total tokens, and cost per model. Useful for understanding which models are driving your spending.

Recent Requests

A log of individual AI requests with the model used, token count, cost, response time, and timestamp. Filter by keyword to find specific requests.