SearXNG Search

Self-hosted, privacy-respecting web search via Docker

TL;DR Run cd searxng && start.bat to start the search engine, then use /searxng on from the CLI.

Overview

SearXNG is a free, privacy-respecting metasearch engine. This project provides a Docker-based setup so you can run your own instance locally, avoiding reliance on public instances (which increasingly return 403/429 due to Cloudflare/anti-bot protection).

Quick Start

cd searxng
start.bat

Starts SearXNG on http://localhost:18889.

Slash Command

Command	Action
`/searxng on`	Start the Docker container
`/searxng off`	Stop the Docker container
`/searxng status`	Check if running
`/searxng restart`	Restart the container

Manual Docker Commands

docker compose -f searxng/docker-compose.yml up -d
docker compose -f searxng/docker-compose.yml down
docker compose -f searxng/docker-compose.yml logs -f

Files

File	Purpose
`searxng/docker-compose.yml`	Container definition, port 18889 → 8080
`searxng/.env`	Host, port, and secret key
`searxng/config/settings.yml`	SearXNG configuration with JSON API enabled
`searxng/limiter.toml`	Rate limiter — relaxed for local network IPs
`searxng/start.bat`	Start wrapper
`searxng/stop.bat`	Stop wrapper
`searxng/restart.bat`	Restart wrapper
`searxng/logs.bat`	Log tail wrapper

How It Works

SearXNG runs in Docker on localhost:18889
The project's .env sets SEARXNG_INSTANCE_URL=http://localhost:18889
selectBestDirectProvider() in WebSearchTool.ts auto-detects this and prioritises SearXNG
The SearXNGProvider sends GET requests with format=json and parses results

Engines Enabled

DuckDuckGo — primary general search (no API key needed)
Google — general search
Wikipedia — infobox and article results
StackOverflow — technical Q&A
GitHub — repository search
Wikidata — structured data infoboxes

Additional engines can be added in searxng/config/settings.yml under the engines: section.

Provider Selection Priority

When performing a web search, the system selects the best available provider:

Tavily — requires TAVILY_API_KEY
Brave — requires BRAVE_API_KEY
Serper — requires SERPER_API_KEY
SearXNG — only if SEARXNG_INSTANCE_URL is explicitly set
DuckDuckGo — always available, free, no API key

Why not auto-select? Public SearXNG instances are intentionally excluded from auto-selection because almost all of them are behind Cloudflare or other anti-bot protection. The provider is only considered available when a self-hosted URL is configured.

Troubleshooting

Container won't start

docker compose -f searxng/docker-compose.yml logs

Check for schema errors in settings.yml or limiter.toml.

No results returned

Check that engines are not failing by visiting http://localhost:18889 and performing a search in the web UI.

Port conflict

Change SEARXNG_PORT in searxng/.env and update SEARXNG_INSTANCE_URL in .env to match.

Updating

cd searxng
docker compose pull
docker compose up -d