2dph/skills/web-search/reference/instance-tuning.md

type, status

type	status
howto	current

Tuning the SearXNG instance

The client treats HTTP 200 + results: [] as throttled, not as absence. Fix the cause on the instance you point BRAIN_SEARCH_URL at, or use the optional Compose profile in this repo.

Optional Compose profile

Do not start this on a host that already runs SearXNG — set BRAIN_SEARCH_URL instead (D3).

SEARXNG_SECRET=$(openssl rand -hex 32) docker compose --profile searxng up -d

Pinned image: docker.io/searxng/searxng:2026.8.10-0a118066d. Settings: deploy/searxng/settings.yml + limiter.toml (RFC1918 pass_ip, short suspended_times, formats: [html, json]). No secrets in git. Bind is 127.0.0.1:8888.

Why the client classifies empty as throttled

A default engine set under load answers HTTP 200 with results: [] (sometimes with empty unresponsive_engines). That is indistinguishable from "nothing found" unless the client refuses to call it absence.

Instance-side levers

1. Allow the callers through the limiter (limiter.toml pass_ip). The Compose file uses RFC1918 only.
2. Shorten suspensions (settings.yml search.suspended_times) so a CAPTCHA does not last a day.
3. More than one engine in general. One live engine is a single point of failure. This repo enables bing, google, duckduckgo, wikipedia.
4. Keep the JSON API on. formats: [html, json] must stay.

Verifying

for i in $(seq 10); do
  bin/web/search.go "test $i" -n 1 --refresh --json | jq -r .status
done

Ten lines of ok means the instance is healthy. Any throttled means say nothing about whether the subject exists.