docs: add Perplexica web search provider setup guide by willtwilson · Pull Request #525 · LibreChat-AI/librechat.ai

willtwilson · 2026-03-08T21:41:45Z

Summary

Perplexica is an open-source AI-powered search engine with 15k+ GitHub stars that provides cited, context-aware answers by combining web search with LLM reasoning. LibreChat currently has no documentation for using Perplexica as a search backend, and it is a popular self-hosted alternative for users who prefer a fully open-source stack.

Changes

content/docs/configuration/tools/perplexica.mdx - New setup guide covering:
- Docker Compose deployment (Perplexica + SearXNG)
- MCP integration via librechat.yaml
- v1.12.1 API breaking change: sources: [web] replaces the deprecated focusMode parameter
- NDJSON response parsing example (updateBlock events with JSON Patch ops)
- Troubleshooting table for common issues
content/docs/configuration/tools/meta.json - Adds perplexica entry under the Search section of the sidebar

Why this matters

Perplexica (ItzCrazyKns/Perplexica) is a popular choice in the self-hosted AI community
The focusMode to sources API change in v1.12.1 is a recurring source of confusion; a canonical doc reduces support burden
The NDJSON parsing pattern is needed for custom MCP integrations but not documented upstream

Checklist

MDX frontmatter matches existing tool docs format (title, icon, description)
meta.json follows existing pattern (adds entry to the Search group)
No links to internal systems, home lab IPs, or non-public resources

Perplexica is an open-source AI-powered search engine (15k+ GitHub stars) that provides cited, context-aware answers. This adds a setup guide covering: - Docker Compose deployment with SearXNG backend - MCP integration via librechat.yaml - v1.12.1 API change: sources:["web"] replaces deprecated focusMode - NDJSON response parsing (updateBlock events) - Troubleshooting table Updates configuration/tools/meta.json to list Perplexica under Search. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

vercel · 2026-03-08T21:41:49Z

@willtwilson is attempting to deploy a commit to the LibreChat's projects Team on Vercel.

A member of the Team first needs to authorize it.

Copilot

Pull request overview

Adds a new documentation page describing how to use Perplexica as a web search backend for LibreChat (via MCP), and exposes it in the Tools sidebar under Search.

Changes:

Adds a Perplexica setup guide (Docker Compose, MCP config, API notes, NDJSON parsing, troubleshooting).
Adds perplexica to the Tools → Search sidebar group.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
content/docs/configuration/tools/perplexica.mdx	New Perplexica integration/setup guide including API and NDJSON parsing notes
content/docs/configuration/tools/meta.json	Adds Perplexica to the Search section of the Tools docs sidebar

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-08T21:45:08Z

+      - ./searxng:/etc/searxng
+```
+
+After starting, visit the Perplexica settings UI (typically at `http://localhost:3000`) to configure your chat model and embedding model providers.


This guide points users to the Perplexica settings UI at http://localhost:3000, but the provided compose snippet only publishes port 3001:3001 (and defines only a backend service). Either add the missing frontend/UI service + port mapping, or update the URL/instructions so the documented UI address matches what is actually deployed.

Suggested change

After starting, visit the Perplexica settings UI (typically at `http://localhost:3000`) to configure your chat model and embedding model providers.

After starting, visit the Perplexica settings UI (typically at `http://localhost:3001`) to configure your chat model and embedding model providers.

Fixed in 0fbbfb6 — updated to port 3001 to match the backend-only compose snippet. Also added a note explaining that port 3000 is the Next.js frontend, which is a separate service not included in the minimal deployment snippet shown.

Copilot · 2026-03-08T21:45:09Z

+const rawText = await response.text();
+const blockValues = new Map<string, string>();
+
+for (const line of rawText.split("\n")) {
+  const trimmed = line.trim();


The docs say the NDJSON response is streamed and the answer is assembled incrementally, but this example uses await response.text() which buffers the entire response in memory and only then parses lines. Either update the description to reflect buffered parsing, or switch the example to reading from response.body (streaming) to match the stated behavior and avoid large-memory responses.

Good observation — updated in 0fbbfb6. The description now accurately says the example buffers the full response before parsing, with a brief note that production-scale implementations may prefer streaming via response.body. The await response.text() approach is deliberately kept in the example for simplicity and readability.

Copilot · 2026-03-08T21:45:09Z

+| Field | Description |
+|-------|-------------|
+| `message.content` | The search query |
+| `chatModel` | LLM used to synthesize the answer |
+| `embeddingModel` | Embedding model used for semantic ranking |


The request-body table markup uses leading double pipes (|| ... | ... |), which renders as an extra empty column in standard Markdown/MDX tables. Use single leading pipes (| Field | Description |) (and similarly for the separator and rows) so the table renders correctly.

Fixed in 0fbbfb6 — double leading pipe removed from the request-body table.

Copilot · 2026-03-08T21:45:09Z

+| Issue | Solution |
+|-------|----------|
+| `focusMode is not a valid field` | Upgrade to Perplexica v1.12.1+ and use `sources: ["web"]` |
+| Empty response / no answer blocks | Verify SearXNG is running and reachable from the Perplexica container |


The troubleshooting table also uses leading double pipes (|| ... | ... |), which will render an extra empty column. Switch to standard Markdown table syntax with single leading pipes for the header/separator/rows.

Fixed in 0fbbfb6 — same fix applied to the troubleshooting table.

Copilot · 2026-03-08T21:45:09Z

+    image: itzcrazykns1337/perplexica-backend:main
+    environment:
+      - SEARXNG_API_URL=http://searxng:8080
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    ports:
+      - "3001:3001"
+    depends_on:
+      - searxng
+
+  searxng:
+    image: searxng/searxng:latest


The Docker Compose example uses mutable image tags itzcrazykns1337/perplexica-backend:main and searxng/searxng:latest, which creates a supply-chain risk: future pulls may silently run altered or compromised images that have access to OPENAI_API_KEY and other data. An attacker who compromises or hijacks these tags could exfiltrate secrets or tamper with search results. Pin these images to specific versions or immutable digests so updates happen only when you explicitly review and change the reference.

Added a warning callout in 0fbbfb6 flagging the supply-chain risk of mutable tags, particularly since both containers have access to API keys via environment variables. The note recommends pinning to specific version digests for production deployments. The mutable tags are kept in the example for readability but the risk is now clearly surfaced.

Address review feedback: - Correct port reference from 3000 to 3001 (backend API) - Add note clarifying buffered vs streaming NDJSON parsing - Add security warning about mutable Docker image tags Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 8, 2026 21:41

Copilot started reviewing on behalf of willtwilson March 8, 2026 21:42 View session

Copilot AI reviewed Mar 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add Perplexica web search provider setup guide#525

docs: add Perplexica web search provider setup guide#525
willtwilson wants to merge 2 commits intoLibreChat-AI:mainfrom
willtwilson:feat/perplexica-search-provider

willtwilson commented Mar 8, 2026

Uh oh!

vercel Bot commented Mar 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

willtwilson Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

willtwilson Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

willtwilson Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

willtwilson Mar 8, 2026

Uh oh!

Copilot AI Mar 8, 2026

Uh oh!

willtwilson Mar 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	After starting, visit the Perplexica settings UI (typically at `http://localhost:3000`) to configure your chat model and embedding model providers.
	After starting, visit the Perplexica settings UI (typically at `http://localhost:3001`) to configure your chat model and embedding model providers.

Conversation

willtwilson commented Mar 8, 2026

Summary

Changes

Why this matters

Checklist

Uh oh!

vercel Bot commented Mar 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

willtwilson Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

willtwilson Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

willtwilson Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

willtwilson Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

willtwilson Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants