Setting up SearXNG
Self-hosted web search for Aldwin without a paid API key.
On this page
Aldwin can search the web through a self-hosted SearXNG instance, with no paid search API key. This guide covers what SearXNG is, what you need, how to run it, and how to connect it to Aldwin.
There is no SearXNG step in aldwin setup yet. If SearXNG is already running on your machine on port 8080, Aldwin finds it automatically. You only need to set a URL when you use a different host or port.
What SearXNG is#
SearXNG is a free, open-source search engine you run yourself. Aldwin sends your search to your instance; that instance asks other engines and brings the results back.
Prefer an instance you run yourself. Public SearXNG sites often turn off the format Aldwin needs, so they will not work.
What you need#
- Docker with Compose (Docker Desktop on macOS/Windows, or Docker Engine + Compose on Linux)
- A free port on your machine (this guide uses 8080)
- Aldwin installed (
uv tool install aldwin)
Aldwin does not install Docker or SearXNG for you.
Install Docker once#
| Device | Install |
|---|---|
| macOS | Install Docker Desktop for Mac, open it, and wait until it says Engine is running. |
| Linux | Install Docker Engine and the Compose plugin. |
| Windows | Aldwin itself is not supported on Windows yet. If you use WSL2, install Docker Desktop for Windows with the WSL2 backend, then run the Linux commands inside WSL. |
Check:
docker --version
docker compose versionIf docker is not found after installing Docker Desktop on macOS, open a new terminal. Desktop may put the CLI in ~/.docker/bin; add that to your PATH if needed:
echo 'export PATH="$HOME/.docker/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcStart SearXNG on any device#
These commands work the same on macOS, Linux, and WSL once Docker works.
mkdir -p ~/searxng/core-config && cd ~/searxng
curl -fsSL \
-O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
-O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
cp .env.example .env
cat > core-config/settings.yml <<'EOF'
use_default_settings: true
search:
formats:
- html
- json
server:
limiter: false
secret_key: "replace-me-with-a-long-random-string"
EOF
docker compose up -dReplace secret_key with any long random string. SearXNG refuses to start with the default ultrasecretkey.
JSON must stay enabled (the json line under search.formats above). Without it, Aldwin cannot use the instance.
Check that it works:
curl -s 'http://127.0.0.1:8080/search?q=test&format=json' | head -c 200You should see a short blob of text that includes "results", not an empty response or an error. You can also open http://127.0.0.1:8080 in a browser.
Useful commands:
cd ~/searxng
docker compose ps # status
docker compose logs core # logs if it will not start
docker compose down # stopConnect Aldwin#
In the web app#
- Open Settings from the bottom of the sidebar and choose Search.
- If you used port 8080 above, SearXNG already shows as connected, with nothing to set up.
- Otherwise, select Connect on SearXNG, enter its address, and select Save address.
- If SearXNG is not marked In use, select Use this one.
In the terminal#
If you used port 8080 above, there is nothing to set up: start Aldwin and run /search. SearXNG shows under Connected as found automatically. If you also have a hosted key (for example Tavily), pick SearXNG and choose Use for search. Automatic lets Aldwin choose again.
Option A: /search (different host or port)#
- Run
/searchand pick SearXNG. - At
SearXNG address [http://127.0.0.1:8080]:type your address, or pressEnterfor the default. - Aldwin shows
Checking SearXNG…and checks that the instance answers with JSON. You then see✓ SearXNG connected at <address> · now used for search, or the reason it could not connect.
To change the address later, pick SearXNG and choose Change address. Disconnect forgets a saved address (a SearXNG found automatically on port 8080 has nothing to disconnect).
Option B: config file#
Add this block to ~/.aldwin/config.yaml:
search:
provider: auto
searxng_url: http://127.0.0.1:8080Set provider: searxng if you want to force SearXNG even when a hosted key is present. In chat, /search searxng does the same and saves the choice.
One-liner append (only if you do not already have a search: section):
cat >> ~/.aldwin/config.yaml <<'EOF'
search:
provider: auto
searxng_url: http://127.0.0.1:8080
EOFOption C: environment variable (one terminal session)#
export SEARXNG_URL=http://127.0.0.1:8080Try it#
aldwinAsk something that needs the live web, for example:
Use web_search to look up today's Python release news.
You should see search results with titles, links, and short snippets. If search is not set up, Aldwin tells you how to add a SearXNG URL or a hosted key via aldwin setup.
Alternatives#
- Hosted key (for example Tavily): run
aldwin setupand paste the key when prompted. No SearXNG required. - Both available: with
provider: auto, Aldwin prefers the hosted key over SearXNG.
Privacy notes#
- Searches go to the SearXNG address you use (your machine if you follow this guide).
- A local or private SearXNG address is allowed on purpose.
- Details: Privacy.
Troubleshooting#
| Symptom | Fix |
|---|---|
docker: command not found | Install/open Docker Desktop, open a new terminal, or add ~/.docker/bin to PATH. |
| Container keeps restarting | Set a non-default secret_key in core-config/settings.yml, then run docker compose up -d again. |
Could not reach SearXNG (no SearXNG with JSON at ...) | Start SearXNG (docker compose up -d in ~/searxng) and keep json under search.formats, then try /search again. |
| Aldwin says JSON is not enabled | Keep json under search.formats in settings.yml, then restart with docker compose up -d. |
| Aldwin still uses Tavily | Run /search, pick SearXNG, and choose Use for search. |
| Connection refused on 8080 | In ~/searxng, run docker compose ps and wait until the service is up on port 8080. |
| Empty or blocked results | Wait a minute, try a broader query, or switch with /search tavily. |