QWE AI Academy By the end of this guide, you’ll have an open source Perplexity alternative running on your own machine – answering questions with cited sources, no per-query cost if you wire it to a local model. The tool is Perplexica, recently renamed to Vane. One Docker command, a browser tab on localhost:3000, and a setup wizard. That’s the whole install.
Docker Hub still shows both repos under the maintainer account – itzcrazykns1337/vane and itzcrazykns1337/perplexica – so older blog posts, compose files, and registry references using the Perplexica name still work after the rebrand (per the official GitHub README). Most tutorials online still tell you to clone the repo and edit a config.toml. You don’t need to do that anymore.
What changed in v1.12.1 (and why it matters)
As of April 2026, the latest tagged release is v1.12.1 (Dec 31, 2025) – it adds an LM Studio provider and fixes function-calling behavior with OpenAI-compatible endpoints. The bigger structural break was v1.12.0 the week before.
v1.12.0 removed LangChain entirely and replaced it with custom base and provider classes built around streamText, streamObject, generateText, and generateObject primitives (per the GitHub releases page). If you maintained a fork that hooked into LangChain callbacks, that’s gone. No migration shim exists – you’re rewriting against the new abstractions. “Providers” also became “connections” in the UI, so older screenshots no longer match.
The LangChain removal is worth sitting with for a moment. A lot of the community tooling – custom retrieval chains, callback hooks, integration plugins – was built on those abstractions. The upgrade isn’t a config change; it’s a rewrite. If you’re on a stock install with no custom code, you won’t feel it. If you forked and extended, check your chains before pulling v1.12.
v1.11.0, back in October 2025, is the release that quietly killed every “clone the repo” tutorial: it introduced a setup wizard and a single-command Docker install path, confirmed in the release notes.
System requirements
1 GB RAM, 1 vCPU – that’s the floor for the bundled image, per Railway’s deployment notes. Both amd64 and arm64 are supported, so a Raspberry Pi 5 or Apple Silicon Mac works fine. Your AI provider (Ollama, OpenAI, Claude) brings its own RAM bill on top.
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2+ vCPU |
| RAM | 1 GB | 2-4 GB (more if running local LLMs) |
| OS / arch | Any Docker host | linux/amd64 or linux/arm64 |
| Docker | Any recent Engine | Latest stable |
Install: the one command that does everything
Skip the repo clone. Skip the config.toml. Run this:
docker run -d
-p 3000:3000
-v vane-data:/home/vane/data
--name vane
--restart unless-stopped
itzcrazykns1337/vane:latestPulls the image, starts the container, bundles SearxNG. Open http://localhost:3000. Setup wizard. Set your API keys and models. Done – no additional steps (per the official README).
Prefer the old image name? itzcrazykns1337/perplexica:latest still publishes. Same code, different label.
Alternative: slim image with an external SearxNG
Already running SearxNG in your homelab and don’t want a second copy:
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-latestTurns out SearxNG ships with JSON output off by default. The slim image requires JSON format enabled – easy to miss because the official docs mention it briefly. If you skip it: Perplexica returns empty results with no error message. Fix is under settings.yml → search.formats → add json.
First-time configuration
The setup wizard is at localhost:3000 on first boot. Pick a chat model provider, optionally an embedding model, paste API keys.
Supported connections as of v1.12.1 (per the official README): OpenAI, Anthropic Claude, Google Gemini, Groq, DeepSeek, Ollama, Lemonade, LM Studio, and AIMLAPI. Mix and match – chat model and embedding model don’t have to come from the same provider.
On embedding models: If you plan to upload documents, consider a small local option like
nomic-embed-textvia Ollama (a popular choice as of early 2026). Embedding every uploaded PDF through a paid API adds up, and retrieval quality over your own files doesn’t meaningfully depend on which embedding model you use.
Verify it works
Three checks, in order of importance:
1. Container status.docker ps | grep vane – you want Up, not Restarting. Restarting usually means a config parse failure (more on that in the FAQ).
2. UI loads. Hit http://localhost:3000. Chat box present? Next.js app is healthy.
3. Citations appear. Ask something with a recent factual answer – “latest Node.js LTS version” works well. If citation chips appear under the response, SearxNG is reachable. No citations, no error? Almost always a SearxNG JSON format issue.
Check Settings for a version field – added in v1.12.0. Blank version means you’re on an old image.
The Ollama trap (and how to fix it)
Most common failure mode. You install Ollama on the host, run a model, see “Failed to connect to server” in Perplexica’s UI. The docs aren’t loud enough about why.
By default, Ollama binds to 127.0.0.1:11434. Only processes on the same machine can reach it. The Vane container runs in a different network namespace – it can’t reach 127.0.0.1 on the host. This is documented in the GitHub issue #544 thread.
Fix on Linux:
sudo systemctl edit ollama
# Add:
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
sudo systemctl daemon-reload
sudo systemctl restart ollamaThen in Perplexica’s settings, Ollama API URL → http://host.docker.internal:11434. Not localhost. Not 127.0.0.1.
On Linux, host.docker.internal isn’t automatically resolved inside containers. Add --add-host=host.docker.internal:host-gateway to your docker run command. Docker Desktop on Mac and Windows handles this automatically.
Other common errors
- “You haven’t configured any chat model providers” – three things to check: server is bound to
0.0.0.0(not127.0.0.1), model name matches exactly what your local LLM server has loaded, and the API key field isn’t empty (even if no key is required, put a placeholder value). - 502 from your reverse proxy – the container needs time on first boot to initialize SearxNG. Wait, reload. If it persists, make sure nginx has
UpgradeandConnectionheaders set – WebSockets are required. - Empty search results, no error – almost always SearxNG JSON format not enabled (slim image), or your host firewall blocking port 8080 internally.
Upgrade and uninstall
Pull, stop, remove, re-run:
docker pull itzcrazykns1337/vane:latest
docker stop vane && docker rm vane
docker run -d
-p 3000:3000
-v vane-data:/home/vane/data
--name vane
--restart unless-stopped
itzcrazykns1337/vane:latestThe vane-data volume carries config and chat history forward – untouched by the upgrade. One caveat: if you’re coming from a pre-v1.12 install with a mounted config.toml, the new parser may reject keys that no longer exist. Remove the config file mount and let the wizard read your data volume instead.
To uninstall completely:
docker stop vane && docker rm vane
docker volume rm vane-data # WARNING: deletes search history + config
docker rmi itzcrazykns1337/vane:latestFAQ
Is Perplexica fully offline-capable?
Partially. Ollama handles the LLM side locally. But SearxNG – even the bundled copy – still hits public search engines (Google, Bing, etc.) for results. Pure airgap isn’t what this tool is designed for.
Why does my container restart in a loop after upgrading from v1.10 to v1.12?
v1.12.0 renamed “providers” to “connections” internally. If you mounted an old config.toml from a manual install, the startup parser rejects the unknown keys and crashes – which Docker restarts, which crashes again. The fix: drop the config file mount entirely. The setup wizard reads config from the vane-data volume, not from a mounted TOML file. If you originally installed via docker compose with a custom config file, remove the mount line and run the wizard once to reconfigure. You’ll re-enter your API keys, but your chat history stays in the volume.
Can I run Perplexica on a Raspberry Pi?
Yes – linux/arm64 image is published. A Pi 5 with 8 GB RAM handles the UI and bundled SearxNG without issues. Don’t run a 7B model on the same Pi; offload that to another machine or use a hosted API.
Next step: run the install command above, open localhost:3000, paste in a Groq API key (free tier as of early 2026), and ask it something you’d normally ask Perplexity. You’ll know within 60 seconds whether this replaces your paid subscription.