Skip to content
Guide

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#

DeviceInstall
macOSInstall Docker Desktop for Mac, open it, and wait until it says Engine is running.
LinuxInstall Docker Engine and the Compose plugin.
WindowsAldwin 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 version

If 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 ~/.zshrc

Start 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 -d

Replace 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 200

You 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        # stop

Connect Aldwin#

In the web app#

  1. Open Settings from the bottom of the sidebar and choose Search.
  2. If you used port 8080 above, SearXNG already shows as connected, with nothing to set up.
  3. Otherwise, select Connect on SearXNG, enter its address, and select Save address.
  4. 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)#

  1. Run /search and pick SearXNG.
  2. At SearXNG address [http://127.0.0.1:8080]: type your address, or press Enter for the default.
  3. 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:8080

Set 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
EOF

Option C: environment variable (one terminal session)#

export SEARXNG_URL=http://127.0.0.1:8080

Try it#

aldwin

Ask 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 setup and 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#

SymptomFix
docker: command not foundInstall/open Docker Desktop, open a new terminal, or add ~/.docker/bin to PATH.
Container keeps restartingSet 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 enabledKeep json under search.formats in settings.yml, then restart with docker compose up -d.
Aldwin still uses TavilyRun /search, pick SearXNG, and choose Use for search.
Connection refused on 8080In ~/searxng, run docker compose ps and wait until the service is up on port 8080.
Empty or blocked resultsWait a minute, try a broader query, or switch with /search tavily.
Was this page helpful?