@clinkai/dsh-web-search-searxng
A SearXNG-backed web_search provider for the DeepSeek Harness web capability seam (ctx.web) — with automatic fallback to another provider (by default the built-in DeepSeek search) when SearXNG is unreachable.
One package, two providers on the public seam:
| provider id | behaviour |
|---|
searxng | pure SearXNG: GET {baseUrl}/search?q=<query>&format=json |
search-fallback | SearXNG first; retries through fallbackProvider when the backend is down, hangs, answers 5xx, or (opt-in) returns nothing |
Pin the seam to whichever one you want with web.searchProvider. Nothing here patches DSH source or imports a DSH-internal export, so a DSH upgrade overwrites nothing.
- No API key, no billing — SearXNG aggregates many engines for free.
- Never leaves search broken — if Docker/SearXNG is down,
search-fallback transparently uses the built-in DeepSeek search.
Run SearXNG
SearXNG has no native Windows support, so run it with Docker (docker compose up -d):
services:
searxng:
image: searxng/searxng:latest
container_name: searxng
ports:
- "127.0.0.1:18081:8080" # 8080 is usually taken by the DSH Web GUI
volumes:
- ./config:/etc/searxng:rw
restart: unless-stopped
Make sure format=json is enabled in config/settings.yml:
search:
formats:
- html
- json
Engine notes (measured, not guessed)
- Domestic engines are off by default.
sogou and 360search answer fine without any proxy, but SearXNG ships them disabled; enable them explicitly or a default search returns nothing while the reachable engines are all blocked ones.
google works whenever the host tunnel is up (or when you point the engine at a local proxy, see below); it periodically gets CAPTCHA-suspended on a shared VPN exit and recovers by itself.brave (HTTP 429), duckduckgo and quark (CAPTCHA) are bot-blocked — a proxy does not fix that.- An engine that failed while DNS/tunnel was not ready is marked Suspended by SearXNG for a while; restart the container before concluding "it cannot connect".
Per-engine proxy (keep domestic engines direct, send only the blocked ones through a local proxy client):
engines:
- name: sogou
disabled: false
- name: google
disabled: false
proxies:
all://:
- http://host.docker.internal:12000
timeout: 8.0
Install
The package ships a dsh.bundle.patch, so installing it is enough: DSH mounts the
providers as a bundle layer and there is nothing to hand-wire.
# from npm (once published)
dsh plugin --profile web add @clinkai/dsh-web-search-searxng
# straight from GitHub — no registry needed, the built entry is committed
dsh plugin --profile web add github:w384/clinkai-dsh-web-search-searxng
# from a local checkout, or from a packed tarball
dsh plugin --profile web add link:/path/to/clinkai-dsh-web-search-searxng
dsh plugin --profile web add ./clinkai-dsh-web-search-searxng-0.2.0.tgz
Override the row by id to pin this instance's SearXNG origin, and point the seam at
one of the two providers. In $DSH_HOME/profiles/<profile>/cordis.patch.yml:
- id: web-search-searxng
config:
baseUrl: http://127.0.0.1:18081
fallbackOnEmpty: true
- id: web
config:
searchProvider: search-fallback # or: searxng
Config
| key | default | meaning |
|---|
baseUrl | http://127.0.0.1:8080 | SearXNG origin |
timeoutMs | 15000 | per-request timeout for the SearXNG call |
fallbackEnabled | true | register the search-fallback provider |
fallbackProvider | deepseek-official | provider id the dispatcher retries through |
fallbackOnEmpty | false | treat an empty SearXNG result as a failure and retry the fallback |
When it falls back
- Connection-level failure — Docker / SearXNG is down (
ECONNREFUSED / ETIMEDOUT / ENOTFOUND …; walks the full cause chain).
- Timeout — SearXNG hung and the caller did not cancel.
- HTTP 5xx — SearXNG is up but failing.
- Empty result — only when
fallbackOnEmpty: true.
Anything else (a caller cancellation, a 4xx like a bad request) is passed through unchanged.
The searxng and deepseek-official providers must both stay registered — their own plugins —
because the dispatcher reads them from the seam registry at call time.
Troubleshooting
- Port 8080 conflict — the DSH Web GUI itself binds
127.0.0.1:8080 by default, so a SearXNG port mapping on 8080 silently fails (the container runs but is unreachable). Use a different host port (e.g. 18081) and set baseUrl accordingly.
- Windows reserved port ranges — Hyper-V/WSL NAT reserves ranges (e.g.
8804-8903), and binding inside one fails with bind: An attempt was made to access a socket in a way forbidden by its access permissions even though nothing listens. Check with netsh interface ipv4 show excludedportrange protocol=tcp.
License
MIT
