How to use SearXNG for web search in BoltAI

SearXNG is a search engine you run yourself. BoltAI can use it for web search with no API key: searches go from your Mac straight to your SearXNG server.

This guide sets up SearXNG with Docker and connects it to BoltAI. If you only want web search with no setup at all, use the DuckDuckGo Search plugin instead.

Before you start

• You need Docker Desktop (or another way to run SearXNG).

• BoltAI needs SearXNG to return results as JSON. This is off by default in SearXNG, and it is the most common reason the connection fails. Step 1 turns it on.

Step 1: Create the settings file

Create a folder for SearXNG, and inside it a file named settings.yml with this single line:

{use_default_settings: true, server: {secret_key: "replace-this-with-a-long-random-string", limiter: false}, search: {formats: [html, json]}}

The json entry in formats is the part BoltAI needs. Replace the secret key with any long random text.

Step 2: Start SearXNG

In Terminal, go to that folder and run this as one line:

docker run -d --name searxng -p 127.0.0.1:8888:8080 -v "$PWD/settings.yml:/etc/searxng/settings.yml:ro" searxng/searxng:latest

SearXNG is now running at http://localhost:8888, reachable only from your Mac. Open that address in a browser to check that the search page loads.

Step 3: Connect it in BoltAI

• Open BoltAI → Settings → Plugins → SearXNG Search.

• Enter the server address: http://localhost:8888

• Click Test and Save.

BoltAI runs a test search. When it shows "Saved. The server is working.", the plugin is ready.

The address is kept on this Mac only. It does not sync to your other devices, because it usually points at this Mac or your local network.

Step 4: Use it in a chat

• Open a chat and click the Tools button in the composer.

• Turn on tools, then turn on SearXNG Search.

• Ask something that needs current information.

SearXNG Search only appears in the Tools menu after you have saved a server address. Web Fetch is turned on alongside it, so the model can read the pages it finds.

It works with every provider, including Local Models. Small local models are less reliable at deciding when to search, so a larger model gives better results.

If it doesn't work

• "This SearXNG server does not allow JSON results": the json format is missing from settings.yml, or the container was started before you added it. Fix the file, then run docker restart searxng.

• Could not connect: check that the container is running (docker ps) and that the address and port in BoltAI match the ones in the docker run command.

• Few or no results: SearXNG collects results from other search engines, and some of them limit requests for a while. Try again in a few minutes, or turn on more engines in SearXNG's preferences.

• Public SearXNG servers: most of them turn JSON off and block automated requests, so they usually will not work. Run your own.