# Project pack: Vane (formerly Perplexica) @ 348feca

Facts about **Vane (formerly Perplexica)** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Vane (until recently called Perplexica) works like Perplexity: you ask a question in plain words, it searches the web privately through its own built-in SearXNG, reads the pages and writes an answer with numbered sources. It can also search discussions or academic papers, look at files you upload, and show images, videos, weather and news. Use a free local model through Ollama or your own key for OpenAI, Claude, Gemini or Groq.

## Version and source
- Repository: https://github.com/ItzCrazyKns/Vane
- Pinned commit: `348feca3e378fb4157b217724ed508dc707f853f`. Use exactly this version.
- Get it: `git clone https://github.com/ItzCrazyKns/Vane perplexica && cd perplexica && git checkout 348feca3e378fb4157b217724ed508dc707f853f`
- Or download a zip: https://github.com/ItzCrazyKns/Vane/archive/348feca3e378fb4157b217724ed508dc707f853f.zip
- Official docs: https://github.com/ItzCrazyKns/Vane/tree/348feca3e378fb4157b217724ed508dc707f853f/docs
- Licence: **MIT**. Very permissive. You can use, change and share it, even commercially, as long as you keep the copyright notice. No obligation to publish your changes.

## Running it
- Easiest:

  ```sh
  docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest # then open http://localhost:3000 and add your model provider (Ollama, OpenAI, Anthropic…) in the setup screen
  ```

- Needs: Docker (the image includes SearXNG), or Node.js with your own SearXNG instance, An AI provider key, or Ollama / LM Studio / Lemonade running locally
- Develop: `npm i && npm run dev   # http://localhost:3000; needs a SearXNG with JSON output enabled (set its URL in settings or SEARXNG_API_URL)`
- Check/lint: `npm run lint`
- Build: `npm run build`
- Stack: typescript (Next.js 16, React, Tailwind CSS, Drizzle ORM). Difficulty for a non-developer with an AI: **moderate**. A single, small Next.js app (about 240 files) with clear folders for the search pipeline, prompts, widgets and model providers. Models, theme, units and personal instructions are set in the app's settings screen. Code changes only need Node and npm; there are no automated tests.

## The project's own AI instructions
Read these in the repository before changing code: `CONTRIBUTING.md`, `docs/architecture/README.md`.

## Customisation points (settings → extend → code)
- **providers-and-models** [settings]: Add Ollama, OpenAI, Anthropic, Gemini, Groq, LM Studio or Lemonade, and choose chat and embedding models. → `Settings → Models (src/components/Settings/Sections/Models/); stored in data/config.json`
- **preferences** [settings]: Light or dark, units, and which extras appear on the home screen. → `Settings → Preferences (theme, metric or imperial units, auto image/video search, weather and news widgets); src/lib/config/index.ts`
- **system-instructions** [settings]: Standing instructions for every answer, e.g. "UK sources first, short answers, British spelling". → `Settings → Personalization → System Instructions`
- **search-modes-and-sources** [settings]: Quick answers or deeper research, and where to look. → `Message box → Speed / Balanced / Quality, and sources (web, discussions, academic)`
- **browser-search-engine** [extend]: Use it straight from the address bar instead of Google. → `Add http://localhost:3000/?q=%s as a search engine in your browser (README)`
- **search-api** [extend]: Ask questions from scripts, shortcuts or other apps and get answers with sources. → `POST /api/search (docs/API/SEARCH.md)`
- **searxng-engines** [extend]: Choose which search engines are used, e.g. turn off ones you don't trust. → `searxng/settings.yml (bundled SearXNG), or your own SearXNG instance with the slim image`
- **prompts** [code]: How questions are understood, researched and written up. → `src/lib/prompts/search/ (classifier.ts, researcher.ts, writer.ts)`
- **widgets** [code]: Add an answer card, like the existing weather, stocks and calculator widgets. → `src/lib/agents/search/widgets/ + src/components/Widgets/`
- **research-actions** [code]: New research steps or sources, e.g. searching one favourite website. → `src/lib/agents/search/researcher/actions/ (registry.ts, search/*.ts)`

## Must keep working
- Saved chats and search history in data/db.sqlite. Database changes need a Drizzle migration in drizzle/.
- Sources and citations. Answers must keep their numbered links to the pages used.
- The /api/search endpoint and the ?q= search URL, which browsers and scripts rely on.
- Run npm run format:write before committing, as CONTRIBUTING.md asks.

## Staying updatable
Providers, preferences, system instructions and the search API cover most personal needs without a fork. The project was renamed from Perplexica to Vane (GitHub redirects ItzCrazyKns/Vane to ItzCrazyKns/Vane, and the Docker image is now itzcrazykns1337/vane). It is mostly a one-person project, so keep larger personal changes in your own copy.

## Data, costs and safety
- Personal data: **yes**. Stored in: Search history and chats in SQLite (data/db.sqlite), settings and API keys in data/config.json, and uploaded files under the data folder. In Docker all of this is in the vane-data volume (/home/vane/data). Your search history can say a lot about you (health, money, worries). Back up the vane-data volume, and delete old chats from the Library if you don't want them kept.
- Service: SearXNG (bundled in the Docker image) (required, free, self-hosted): Private web, image and video search. The slim image can use your own SearXNG instead.
- Service: Chat and embedding models (OpenAI, Anthropic, Gemini, Groq, or OpenAI-compatible) (optional, pay-per-use with your own key): Reads the search results and writes the answer. One provider, cloud or local, is needed.
- Service: Ollama, LM Studio or Lemonade (optional, free (uses your own computer)): Run the AI locally so questions and answers stay on your machine.
- Service: Local Transformers embeddings (optional, free): Built-in embedding models for ranking results and searching uploads without a cloud key.
- Setting `SEARXNG_API_URL`: Address of your own SearXNG (only needed with the slim image or a non-Docker install).
- Setting `OLLAMA_BASE_URL`: Address of your Ollama server, e.g. http://host.docker.internal:11434. Can also be set in the setup screen.
- Setting `OPENAI_API_KEY` (**secret**: the person enters it themselves, never in chat): OpenAI key, if you use OpenAI. Usually entered in the setup screen instead.
- Setting `OPENAI_BASE_URL`: Base URL for an OpenAI-compatible provider.
- Setting `DATA_DIR`: Folder holding data/config.json and data/db.sqlite (set by the Docker image).
- Vane has no login at all. Anyone who can reach port 3000 can use your AI keys and read your search history. Keep it on your home network, or put it behind a reverse proxy with a password and HTTPS.
- Your question and the pages found are sent to the AI provider you choose. Use Ollama or another local model to keep everything at home; the web searches themselves go out through SearXNG to engines like Google, Bing and DuckDuckGo without your identity.
- API keys are stored in plain text in data/config.json inside the vane-data volume. Don't share that volume or paste it into an AI chat.
- Development is slower in 2026 (one main maintainer), so check for security updates before exposing it.

---

# Customising Vane (formerly Perplexica)

Vane is one small Next.js app. The search pipeline lives in `src/lib/agents/search/`, the prompts in `src/lib/prompts/`, and the screens in `src/app/` and `src/components/`. **Models, look and answer style are settings.** Exhaust levels 1 and 2 before touching code.

> The project was renamed from Perplexica to Vane after this listing's repo name was chosen. GitHub redirects `ItzCrazyKns/Vane` to `ItzCrazyKns/Vane`, and the Docker image is `itzcrazykns1337/vane`.

## Level 1: Settings (no code)
- **Setup screen and Settings → Models:** add providers (Ollama, OpenAI, Anthropic, Gemini, Groq, LM Studio, Lemonade, local Transformers embeddings) and choose the chat and embedding models. Everything is saved in `data/config.json`.
- **Settings → Preferences:** light or dark theme, metric or imperial, automatic image and video search, weather and news widgets.
- **Settings → Personalization → System Instructions:** standing instructions for every answer (tone, length, language, favourite sources).
- **Settings → Search:** the SearXNG address (only needed with the slim image).
- **In the message box:** Speed, Balanced or Quality mode, and which sources to use (web, discussions, academic).

## Level 2: Extend (no fork)
- **Browser search engine:** add `http://localhost:3000/?q=%s` as a custom search engine.
- **Search API:** `POST /api/search` (see `docs/API/SEARCH.md`) returns an answer and its sources. Good for phone shortcuts, chat bots or a smart speaker.
- **SearXNG engines:** the bundled SearXNG uses `searxng/settings.yml`. With the slim image you can run your own SearXNG and choose its engines (JSON output and the Wolfram Alpha engine must be on).

## Level 3: Code
Read `CONTRIBUTING.md` and `docs/architecture/README.md` first.

| Change | Where |
|---|---|
| How answers are written | `src/lib/prompts/search/writer.ts` (classifier.ts and researcher.ts for the earlier steps) |
| New research step or source | `src/lib/agents/search/researcher/actions/` (register it in `registry.ts`) |
| New answer card | `src/lib/agents/search/widgets/` + `src/components/Widgets/` |
| Home screen | `src/components/EmptyChat.tsx`, `src/components/EmptyChatMessageInput.tsx` |
| Chat screen | `src/components/ChatWindow.tsx`, `src/components/MessageBox.tsx` |
| Settings screens | `src/components/Settings/**`, options in `src/lib/config/index.ts` |
| New model provider | `src/lib/models/providers/<name>/` + `src/lib/models/providers/index.ts` |
| Data | `src/lib/db/schema.ts` + a migration in `drizzle/` |
| Styles | `src/app/globals.css`, `tailwind.config.ts` |

## Running locally
- **Just use it:** `docker run -d -p 3000:3000 -v vane-data:/home/vane/data --name vane itzcrazykns1337/vane:latest`, then open http://localhost:3000.
- **Develop:**
  1. Run a SearXNG with JSON output enabled (or the slim Docker image's instructions).
  2. Run `npm i`.
  3. Run `npm run dev` and open http://localhost:3000.
  4. Enter the SearXNG URL and a model provider in the setup screen.
- **Check:** `npm run lint`, `npm run build`, and `npm run format:write` before committing. There is no test suite.

## Pitfalls
- There is no login. Never put it on the open internet without a password-protected reverse proxy.
- From inside Docker, Ollama on your own computer is `http://host.docker.internal:11434` (on Linux, use your computer's network address and make Ollama listen on 0.0.0.0).
- Local OpenAI-compatible servers need a non-empty API key field, even if they ignore it.
- Keep the `vane-data` volume when updating, or you lose settings and history.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/perplexica/348feca/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/perplexica/348feca/SKILL.md)