Vane Documentation

File: README.md Copy Chapter

Vane 🔍

Vane is a privacy-focused AI answering engine that runs entirely on your own hardware. It combines knowledge from the vast internet with support for local LLMs (Ollama) and cloud providers (OpenAI, Claude, Groq), delivering accurate answers with cited sources while keeping your searches completely private.

Want to know more about its architecture and how it works? You can read it here.

✨ Features Copy Chapter

🤖 Support for all major AI providers - Use local LLMs through Ollama or connect to OpenAI, Anthropic Claude, Google Gemini, Groq, and more. Mix and match models based on your needs.

⚡ Smart search modes - Choose Speed Mode when you need quick answers, Balanced Mode for everyday searches, or Quality Mode for deep research.

🧭 Pick your sources - Search the web, discussions, or academic papers. More sources and integrations are in progress.

🧩 Widgets - Helpful UI cards that show up when relevant, like weather, calculations, stock prices, and other quick lookups.

🔍 Web search powered by SearxNG - Access multiple search engines while keeping your identity private. Support for Tavily and Exa coming soon for even better results.

📷 Image and video search - Find visual content alongside text results. Search isn't limited to just articles anymore.

📄 File uploads - Upload documents and ask questions about them. PDFs, text files, images - Vane understands them all.

🌐 Search specific domains - Limit your search to specific websites when you know where to look. Perfect for technical documentation or research papers.

💡 Smart suggestions - Get intelligent search suggestions as you type, helping you formulate better queries.

📚 Discover - Browse interesting articles and trending content throughout the day. Stay informed without even searching.

🕒 Search history - Every search is saved locally so you can revisit your discoveries anytime. Your research is never lost.

✨ More coming soon - We're actively developing new features based on community feedback. Join our Discord to help shape Vane's future!

Sponsors Copy Chapter

Vane's development is powered by the generous support of our sponsors. Their contributions help keep this project free, open-source, and accessible to everyone.

We'd also like to thank the following partners for their generous support:

Installation Copy Chapter

There are mainly 2 ways of installing Vane - With Docker, Without Docker. Using Docker is highly recommended.

Getting Started with Docker (Recommended) Copy Section

Vane can be easily run using Docker. Simply run the following command:

docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest

This will pull and start the Vane container with the bundled SearxNG search engine. Once running, open your browser and navigate to http://localhost:3000. You can then configure your settings (API keys, models, etc.) directly in the setup screen.

Note: The image includes both Vane and SearxNG, so no additional setup is required. The -v flags create persistent volumes for your data and uploaded files.

Using Vane with Your Own SearxNG Instance

If you already have SearxNG running, you can use the slim version of Vane:

docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:slim-latest

Important: Make sure your SearxNG instance has:

• JSON format enabled in the settings
• Wolfram Alpha search engine enabled

Replace http://your-searxng-url:8080 with your actual SearxNG URL. Then configure your AI provider settings in the setup screen at http://localhost:3000.

Advanced Setup (Building from Source)

If you prefer to build from source or need more control:

1. Ensure Docker is installed and running on your system.

2. Clone the Vane repository:

   bash Copy

   git clone https://github.com/ItzCrazyKns/Vane.git

3. After cloning, navigate to the directory containing the project files.

4. Build and run using Docker:

   bash Copy

   docker build -t vane .
   docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane vane

5. Access Vane at http://localhost:3000 and configure your settings in the setup screen.

Note: After the containers are built, you can start Vane directly from Docker without having to open a terminal.

Non-Docker Installation Copy Section

1. Install SearXNG and allow JSON format in the SearXNG settings. Make sure Wolfram Alpha search engine is also enabled.

2. Clone the repository:

   bash Copy

   git clone https://github.com/ItzCrazyKns/Vane.git
   cd Vane

3. Install dependencies:

   bash Copy

   npm i

4. Build the application:

   bash Copy

   npm run build

5. Start the application:

   bash Copy

   npm run start

6. Open your browser and navigate to http://localhost:3000 to complete the setup and configure your settings (API keys, models, SearxNG URL, etc.) in the setup screen.

Note: Using Docker is recommended as it simplifies the setup process, especially for managing environment variables and dependencies.

See the installation documentation for more information like updating, etc.

Troubleshooting Copy Section

Local OpenAI-API-Compliant Servers

If Vane tells you that you haven't configured any chat model providers, ensure that:

1. Your server is running on 0.0.0.0 (not 127.0.0.1) and on the same port you put in the API URL.
2. You have specified the correct model name loaded by your local LLM server.
3. You have specified the correct API key, or if one is not defined, you have put something in the API key field and not left it empty.

Ollama Connection Errors

If you're encountering an Ollama connection error, it is likely due to the backend being unable to connect to Ollama's API. To fix this issue you can:

1. Check your Ollama API URL: Ensure that the API URL is correctly set in the settings menu.

2. Update API URL Based on OS:

   • Windows: Use http://host.docker.internal:11434
   • Mac: Use http://host.docker.internal:11434
   • Linux: Use http://:11434

   Adjust the port number if you're using a different one.

3. Linux Users - Expose Ollama to Network:

   • Inside /etc/systemd/system/ollama.service, you need to add Environment="OLLAMA_HOST=0.0.0.0:11434". (Change the port number if you are using a different one.) Then reload the systemd manager configuration with systemctl daemon-reload, and restart Ollama by systemctl restart ollama. For more information see Ollama docs

   • Ensure that the port (default is 11434) is not blocked by your firewall.

Lemonade Connection Errors

If you're encountering a Lemonade connection error, it is likely due to the backend being unable to connect to Lemonade's API. To fix this issue you can:

1. Check your Lemonade API URL: Ensure that the API URL is correctly set in the settings menu.

2. Update API URL Based on OS:

   • Windows: Use http://host.docker.internal:8000
   • Mac: Use http://host.docker.internal:8000
   • Linux: Use http://:8000

   Adjust the port number if you're using a different one.

3. Ensure Lemonade Server is Running:

   • Make sure your Lemonade server is running and accessible on the configured port (default is 8000).
   • Verify that Lemonade is configured to accept connections from all interfaces (0.0.0.0), not just localhost (127.0.0.1).
   • Ensure that the port (default is 8000) is not blocked by your firewall.

Using as a Search Engine Copy Chapter

If you wish to use Vane as an alternative to traditional search engines like Google or Bing, or if you want to add a shortcut for quick access from your browser's search bar, follow these steps:

1. Open your browser's settings.
2. Navigate to the 'Search Engines' section.
3. Add a new site search with the following URL: http://localhost:3000/?q=%s. Replace localhost with your IP address or domain name, and 3000 with the port number if Vane is not hosted locally.
4. Click the add button. Now, you can use Vane directly from your browser's search bar.

Using Vane's API Copy Chapter

Vane also provides an API for developers looking to integrate its powerful search engine into their own applications. You can run searches, use multiple models and get answers to your queries.

For more details, check out the full documentation here.

Expose Vane to network Copy Chapter

Vane runs on Next.js and handles all API requests. It works right away on the same network and stays accessible even with port forwarding.

One-Click Deployment Copy Chapter

Upcoming Features Copy Chapter

• Adding more widgets, integrations, search sources
• Adding ability to create custom agents (name T.B.D.)
• Adding authentication

Support Us Copy Chapter

If you find Vane useful, consider giving us a star on GitHub. This helps more people discover Vane and supports the development of new features. Your support is greatly appreciated.

Donations Copy Section

We also accept donations to help sustain our project. If you would like to contribute, you can use the following options to donate. Thank you for your support!

Contribution Copy Chapter

Vane is built on the idea that AI and large language models should be easy for everyone to use. If you find bugs or have ideas, please share them in via GitHub Issues. For more information on contributing to Vane you can read the CONTRIBUTING.md file to learn more about Vane and how you can contribute to it.

Help and Support Copy Chapter

If you have any questions or feedback, please feel free to reach out to us. You can create an issue on GitHub or join our Discord server. There, you can connect with other users, share your experiences and reviews, and receive more personalized help. Click here to join the Discord server. To discuss matters outside of regular support, feel free to contact me on Discord at itzcrazykns.

Thank you for exploring Vane, the AI-powered search engine designed to enhance your search experience. We are constantly working to improve Vane and expand its capabilities. We value your feedback and contributions which help us make Vane even better. Don't forget to check back for updates and new features!

File: docs/installation/UPDATING.md Copy Chapter

Update Perplexica to the latest version

To update Perplexica to the latest version, follow these steps:

For Docker users (Using pre-built images) Copy Chapter

Simply pull the latest image and restart your container:

docker pull itzcrazykns1337/perplexica:latest
docker stop perplexica
docker rm perplexica
docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest

For slim version:

docker pull itzcrazykns1337/perplexica:slim-latest
docker stop perplexica
docker rm perplexica
docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:slim-latest

Once updated, go to http://localhost:3000 and verify the latest changes. Your settings are preserved automatically.

For Docker users (Building from source) Copy Chapter

1. Navigate to your Perplexica directory and pull the latest changes:

   bash Copy

   cd Perplexica
   git pull origin master

2. Rebuild the Docker image:

   bash Copy

   docker build -t perplexica .

3. Stop and remove the old container, then start the new one:

   bash Copy

   docker stop perplexica
   docker rm perplexica
   docker run -p 3000:3000 -p 8080:8080 --name perplexica perplexica

4. Once the command completes, go to http://localhost:3000 and verify the latest changes.

For non-Docker users Copy Chapter

1. Navigate to your Perplexica directory and pull the latest changes:

   bash Copy

   cd Perplexica
   git pull origin master

2. Install any new dependencies:

   bash Copy

   npm i

3. Rebuild the application:

   bash Copy

   npm run build

4. Restart the application:

   bash Copy

   npm run start

5. Go to http://localhost:3000 and verify the latest changes. Your settings are preserved automatically.

File: docs/architecture/README.md Copy Chapter

Perplexica Architecture

Perplexica is a Next.js application that combines an AI chat experience with search.

For a high level flow, see WORKING.md. For deeper implementation details, see CONTRIBUTING.md.

Key components Copy Chapter

1. User Interface

   • A web based UI that lets users chat, search, and view citations.

2. API Routes

   • POST /api/chat powers the chat UI.
   • POST /api/search provides a programmatic search endpoint.
   • GET /api/providers lists available providers and model keys.

3. Agents and Orchestration

   • The system classifies the question first.
   • It can run research and widgets in parallel.
   • It generates the final answer and includes citations.

4. Search Backend

   • A meta search backend is used to fetch relevant web results when research is enabled.

5. LLMs (Large Language Models)

   • Used for classification, writing answers, and producing citations.

6. Embedding Models

   • Used for semantic search over user uploaded files.

7. Storage

   • Chats and messages are stored so conversations can be reloaded.

File: docs/architecture/WORKING.md Copy Chapter

How Vane Works

This is a high level overview of how Vane answers a question.

If you want a component level overview, see README.md.

If you want implementation details, see CONTRIBUTING.md.

What happens when you ask a question Copy Chapter

When you send a message in the UI, the app calls POST /api/chat.

At a high level, we do three things:

1. Classify the question and decide what to do next.
2. Run research and widgets in parallel.
3. Write the final answer and include citations.

Classification Copy Chapter

Before searching or answering, we run a classification step.

This step decides things like:

• Whether we should do research for this question
• Whether we should show any widgets
• How to rewrite the question into a clearer standalone form

Widgets Copy Chapter

Widgets are small, structured helpers that can run alongside research.

Examples include weather, stocks, and simple calculations.

If a widget is relevant, we show it in the UI while the answer is still being generated.

Widgets are helpful context for the answer, but they are not part of what the model should cite.

Research Copy Chapter

If research is needed, we gather information in the background while widgets can run.

Depending on configuration, research may include web lookup and searching user uploaded files.

Answer generation Copy Chapter

Once we have enough context, the chat model generates the final response.

You can control the tradeoff between speed and quality using optimizationMode:

• speed
• balanced
• quality

How citations work Copy Chapter

We prompt the model to cite the references it used. The UI then renders those citations alongside the supporting links.

Search API Copy Chapter

If you are integrating Vane into another product, you can call POST /api/search.

It returns:

• message: the generated answer
• sources: supporting references used for the answer

You can also enable streaming by setting stream: true.

Image and video search Copy Chapter

Image and video search use separate endpoints (POST /api/images and POST /api/videos). We generate a focused query using the chat model, then fetch matching results from a search backend.

File: docs/API/SEARCH.md Copy Chapter

Vane Search API Documentation

Overview Copy Chapter

Vane's Search API makes it easy to use our AI-powered search engine. You can run different types of searches, pick the models you want to use, and get the most recent info. Follow the following headings to learn more about Vane's search API.

Endpoints Copy Chapter

Get Available Providers and Models Copy Section

Before making search requests, you'll need to get the available providers and their models.

**GET** `/api/providers`

Full URL: http://localhost:3000/api/providers

Returns a list of all active providers with their available chat and embedding models.

Response Example:

{
  "providers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "OpenAI",
      "chatModels": [
        {
          "name": "GPT 4 Omni Mini",
          "key": "gpt-4o-mini"
        },
        {
          "name": "GPT 4 Omni",
          "key": "gpt-4o"
        }
      ],
      "embeddingModels": [
        {
          "name": "Text Embedding 3 Large",
          "key": "text-embedding-3-large"
        }
      ]
    }
  ]
}

Use the id field as the providerId and the key field from the models arrays when making search requests.

Search Query Copy Section

**POST** `/api/search`

Full URL: http://localhost:3000/api/search

Note: Replace localhost:3000 with your Vane instance URL if running on a different host or port

Request Copy Section

The API accepts a JSON object in the request body, where you define the enabled search sources, chat models, embedding models, and your query.

Request Body Structure

{
  "chatModel": {
    "providerId": "550e8400-e29b-41d4-a716-446655440000",
    "key": "gpt-4o-mini"
  },
  "embeddingModel": {
    "providerId": "550e8400-e29b-41d4-a716-446655440000",
    "key": "text-embedding-3-large"
  },
  "optimizationMode": "speed",
  "sources": ["web"],
  "query": "What is Vane",
  "history": [
    ["human", "Hi, how are you?"],
    ["assistant", "I am doing well, how can I help you today?"]
  ],
  "systemInstructions": "Focus on providing technical details about Vane's architecture.",
  "stream": false
}

Note: The providerId must be a valid UUID obtained from the /api/providers endpoint. The example above uses a sample UUID for demonstration.

Request Parameters Copy Section

• chatModel (object, required): Defines the chat model to be used for the query. To get available providers and models, send a GET request to http://localhost:3000/api/providers.

  • providerId (string): The UUID of the provider. You can get this from the /api/providers endpoint response.
  • key (string): The model key/identifier (e.g., gpt-4o-mini, llama3.1:latest). Use the key value from the provider's chatModels array, not the display name.

• embeddingModel (object, required): Defines the embedding model for similarity-based searching. To get available providers and models, send a GET request to http://localhost:3000/api/providers.

  • providerId (string): The UUID of the embedding provider. You can get this from the /api/providers endpoint response.
  • key (string): The embedding model key (e.g., text-embedding-3-large, nomic-embed-text). Use the key value from the provider's embeddingModels array, not the display name.

• sources (array, required): Which search sources to enable. Available values:

  • web, academic, discussions.

• optimizationMode (string, optional): Specifies the optimization mode to control the balance between performance and quality. Available modes:

  • speed: Prioritize speed and return the fastest answer.
  • balanced: Provide a balanced answer with good speed and reasonable quality.
  • quality: Prioritize answer quality (may be slower).

• query (string, required): The search query or question.

• systemInstructions (string, optional): Custom instructions provided by the user to guide the AI's response. These instructions are treated as user preferences and have lower priority than the system's core instructions. For example, you can specify a particular writing style, format, or focus area.

• history (array, optional): An array of message pairs representing the conversation history. Each pair consists of a role (either 'human' or 'assistant') and the message content. This allows the system to use the context of the conversation to refine results. Example:

  json Copy

  [
    ["human", "What is Vane?"],
    ["assistant", "Vane is an AI-powered search engine..."]
  ]

• stream (boolean, optional): When set to true, enables streaming responses. Default is false.

Response Copy Section

The response from the API includes both the final message and the sources used to generate that message.

Standard Response (stream: false)

{
  "message": "Vane is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online. Here are some key features and characteristics of Vane:\n\n- **AI-Powered Technology**: It utilizes advanced machine learning algorithms to not only retrieve information but also to understand the context and intent behind user queries, providing more relevant results [1][5].\n\n- **Open-Source**: Being open-source, Vane offers flexibility and transparency, allowing users to explore its functionalities without the constraints of proprietary software [3][10].",
  "sources": [
    {
      "content": "Vane is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online.",
      "metadata": {
        "title": "What is Vane, and how does it function as an AI-powered search ...",
        "url": "https://askai.glarity.app/search/What-is-Vane--and-how-does-it-function-as-an-AI-powered-search-engine"
      }
    },
    {
      "content": "Vane is an open-source AI-powered search tool that dives deep into the internet to find precise answers.",
      "metadata": {
        "title": "Sahar Mor's Post",
        "url": "https://www.linkedin.com/posts/sahar-mor_a-new-open-source-project-called-vane-activity-7204489745668694016-ncja"
      }
    }
        ....
  ]
}

Streaming Response (stream: true)

When streaming is enabled, the API returns a stream of newline-delimited JSON objects using Server-Sent Events (SSE). Each line contains a complete, valid JSON object. The response has Content-Type: text/event-stream.

Example of streamed response objects:

{"type":"init","data":"Stream connected"}
{"type":"sources","data":[{"content":"...","metadata":{"title":"...","url":"..."}},...]}
{"type":"response","data":"Vane is an "}
{"type":"response","data":"innovative, open-source "}
{"type":"response","data":"AI-powered search engine..."}
{"type":"done"}

Clients should process each line as a separate JSON object. The different message types include:

• init: Initial connection message
• sources: All sources used for the response
• response: Chunks of the generated answer text
• done: Indicates the stream is complete

Fields in the Response Copy Section

• message (string): The search result, generated based on the query and enabled sources.
• sources (array): A list of sources that were used to generate the search result. Each source includes:
  • content: A snippet of the relevant content from the source.
  • metadata: Metadata about the source, including:
    • title: The title of the webpage.
    • url: The URL of the webpage.

Error Handling Copy Section

If an error occurs during the search process, the API will return an appropriate error message with an HTTP status code.

• 400: If the request is malformed or missing required fields (e.g., no sources or query).
• 500: If an internal server error occurs during the search.