Skip to content
Back to search

dsh-searxng

DeepSeek Harness (dsh) plugin that adds a SearXNG-backed web_search provider to the ctx.web seam — free, self-hosted, key-less search instead of paid Exa/Perplexity APIs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rogerdigital--dsh-searxng/badge.svg)](/listings/rogerdigital--dsh-searxng)

HTML

<a href="/listings/rogerdigital--dsh-searxng"><img src="/api/listings/rogerdigital--dsh-searxng/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: Node.js 20 or newer, `dsh`, Docker Engine or Docker Desktop, and Docker Compose v2.

The setup command installs and attaches `dsh-searxng` to the selected profile, so no separate plugin-install step is required.

npx dsh-searxng setup
dsh --profile web

`setup` creates a loopback-only, pinned SearXNG Docker deployment, waits for the JSON API, runs a real search through both SearXNG and the final DSH provider configuration, and only then activates the profile. Repeating the command reuses the same owned container, port, configuration, and secret.

Use another DSH profile or port when needed:

npx dsh-searxng setup --profile research --port 9080
dsh --profile research

Package installation and DSH plugin activation never start Docker. Docker is changed only by an explicit `dsh-searxng setup` or `dsh-searxng remove --service` command.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 264 lines
  1. # dsh-searxng
  2. [![dsh-vet](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Frogerdigital%2Fdsh-searxng%2Fdsh-vet%2Freport%2F.dsh-vet%2Fbadge.json)](https://github.com/rogerdigital/dsh-searxng/blob/dsh-vet/report/.dsh-vet/report.json)
  3. A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin that registers a
  4. [SearXNG](https://docs.searxng.org/)-backed search provider into the web capability seam
  5. (`ctx.web`), giving your agent `web_search` through a **free, self-hosted, key-less** metasearch
  6. instance — instead of the paid Exa/Perplexity APIs.
  7. ## Quick start
  8. Requirements: Node.js 20 or newer, `dsh`, Docker Engine or Docker Desktop, and Docker Compose v2.
  9. The setup command installs and attaches `dsh-searxng` to the selected profile, so no separate
  10. plugin-install step is required.
  11. ```sh
  12. npx dsh-searxng setup
  13. dsh --profile web
  14. ```
  15. `setup` creates a loopback-only, pinned SearXNG Docker deployment, waits for the JSON API, runs a
  16. real search through both SearXNG and the final DSH provider configuration, and only then activates
  17. the profile. Repeating the command reuses the same owned container, port, configuration, and
  18. secret.
  19. Use another DSH profile or port when needed:
  20. ```sh
  21. npx dsh-searxng setup --profile research --port 9080
  22. dsh --profile research
  23. ```
  24. Package installation and DSH plugin activation never start Docker. Docker is changed only by an
  25. explicit `dsh-searxng setup` or `dsh-searxng remove --service` command.
  26. ## Existing SearXNG
  27. An existing local, remote, authenticated, or independently managed SearXNG instance is a
  28. first-class path:
  29. ```sh
  30. npx dsh-searxng setup --profile web --url https://search.example.com
  31. ```
  32. The endpoint must be HTTP(S), contain no credentials, query, or fragment, and enable JSON search.
  33. Existing provider options such as `authHeader`, `language`, `engines`, and `categories` in the DSH
  34. profile are preserved and used by validation. External mode never invokes Docker.
  35. ## Manual plugin installation
  36. If you manage the DSH profile patch yourself and do not want the setup command to attach it,
  37. install only the plugin package:
  38. ```sh
  39. dsh plugin add dsh-searxng
  40. ```
  41. With a named profile, use `dsh plugin --profile <name> add dsh-searxng`.
  42. ## Operations
  43. ```sh
  44. # Fast health result; stops at the first failure.
  45. npx dsh-searxng status --profile web
  46. # Ordered environment, Docker, ownership, HTTP, JSON, search, profile, and provider checks,
  47. # plus the local privacy posture with its explicit out-of-scope limits.
  48. npx dsh-searxng doctor --profile web
  49. # Read-only engine-health probe battery: per-engine reported failures with reasons,
  50. # result contribution, and evidence limits. Writes nothing.
  51. npx dsh-searxng tune --profile web
  52. # Plan and execute ownership-safe repairs for the managed deployment.
  53. npx dsh-searxng repair --profile web
  54. # Move the managed deployment to a packaged version with verified rollback.
  55. npx dsh-searxng update --profile web
  56. # Detach the profile and remove the plugin package from that profile.
  57. npx dsh-searxng remove --profile web
  58. # Also stop and remove the owned service; keep its data and local state.
  59. npx dsh-searxng remove --profile web --service
  60. # Permanently delete the exact owned data volume and managed directory.
  61. npx dsh-searxng remove --profile web --service --purge-data
  62. ```
  63. Permanent deletion prompts on an interactive terminal. Automation must add `--yes`. `--json` is
  64. available on setup, status, doctor, repair, update, and remove. Destructive Docker operations run
  65. only after the container, network, and volume labels match this DSH home; same-name foreign
  66. resources are refused.
  67. ### Recovery semantics
  68. `repair` and `update` journal their progress under
  69. `$DSH_HOME/dsh-searxng/journal.json` between the first mutation and validated completion; `setup`
  70. and `remove` read that journal to refuse during or clean up after an interruption.
  71. - `setup` refuses to run while an interrupted operation is recorded and points at `repair`. When a matching
  72. deployment is recorded but unhealthy, it restarts a wedged runtime, or — if the container is gone while the
  73. recorded bundle survives (the leftover of `remove --service` without `--purge-data`, or a manual
  74. `docker compose down`) — recreates the runtime from that bundle.
  75. - `repair` takes over when a journal exists: it recomputes the recovery decision from disk (clear
  76. the journal, validate the target, or resume the rollback) before any ordinary repair, and also
  77. removes quarantined stale locks left by dead processes. `doctor` reports the interrupted
  78. operation's id, kind, phase, and age.
  79. - `update` is transactional: the current deployment stays authoritative until the target passes
  80. readiness, real-search, and provider validation. Any failure after the first Docker mutation
  81. rolls back to the previous image and configuration and revalidates them; same-version updates
  82. are rejected with `E_DEPLOYMENT_UNSUPPORTED`.
  83. - `remove --service` clears the journal once the deployment is gone, so a subsequent `setup` is
  84. not refused. It also removes the labeled leftovers of a container-less deployment by deriving the
  85. compose file from the bundle recorded in state.
  86. ## Provider configuration
  87. The setup command manages the `web-search-searxng` row in
  88. `$DSH_HOME/profiles/<name>/cordis.patch.yml`. These optional values can be added to that row:
  89. | Key | Default | Meaning |
  90. |---|---|---|
  91. | `baseURL` | managed or `--url` endpoint | SearXNG base URL. |
  92. | `baseURLs` | none | Failover pool of SearXNG base URLs; the first entry is primary and a non-empty list wins over `baseURL`. |
  93. | `language` | none | SearXNG language, for example `zh-CN` or `en-US`. |
  94. | `engines` | none | Comma-separated engine allowlist. |
  95. | `categories` | none | Comma-separated category filter. |
  96. | `authHeader` | none | Authorization header for a protected external instance. |
  97. | `cacheTtlMs` | 600000 | Cached query result lifetime in milliseconds; `0` disables caching. |
  98. | `minIntervalMs` | 1500 | Minimum spacing between network requests; `0` disables pacing. |
  99. | `queueCapacity` | 8 | Requests that may wait for a pacing slot before the provider rejects with backpressure. |
  100. | `totalBudgetMs` | 15000 | Wall-clock budget for one search call, spanning pacing wait, backoff, and network attempts. |
  101. Repeated queries are served from an in-process cache scoped to the provider
  102. instance (nothing is written to disk); a cache hit performs no network request.
  103. Concurrent searches pass a token bucket (burst 2, then one request per
  104. `minIntervalMs`), and a full queue rejects immediately with a retryable error
  105. instead of holding the caller. Failed responses and empty result pages are never cached —
  106. a cached empty page would mask upstream recovery for the whole TTL — and an empty result
  107. page is returned as-is: the `engines`/`categories` allowlist is never
  108. silently widened to chase results. When the instance answers HTTP 429, the
  109. provider honors `Retry-After` and retries at most once within the remaining
  110. budget.
  111. ### Multi-instance failover
  112. List two or more endpoints in `baseURLs` (at most 8, duplicates collapse) to
  113. route searches across them — for example a local managed instance first and a
  114. remote one second:
  115. ```yaml
  116. web-search-searxng:
  117. baseURLs:
  118. - http://127.0.0.1:8080
  119. - https://searxng.example.net
  120. ```
  121. The first entry is primary. When an attempt fails with a network error, a
  122. timeout, or HTTP 502/503/504/429, the endpoint's health penalty rises and the
  123. next attempt (and the first attempt of later searches) goes to the healthiest
  124. endpoint; penalties decay with a 30 s half-life, so the primary recovers the
  125. first slot about a minute after its last failure, or immediately after a
  126. successful search. Malformed responses (`contract` failures) and other 4xx
  127. statuses never fail over — those are configuration problems on that endpoint
  128. that switching would silently mask. The cache is keyed by the whole pool, the
  129. pacing bucket is per endpoint, and the `totalBudgetMs` deadline spans every
  130. endpoint's attempts; empty result pages are valid answers and never trigger
  131. failover. `setup --url` still records a single external endpoint per profile —
  132. configuring a pool is a manual profile-config edit until the CLI follow-up
  133. ships.
  134. ## Per-query controls
  135. SearXNG supports per-query routing inside the query string itself; the provider
  136. passes query syntax through untouched:
  137. - `:zh-CN` / `:en` — select the result language for this query (`:` prefix).
  138. - `!bing` / `!news` — select one engine or category for this query (`!` prefix).
  139. - `site:example.com` — restrict results to one domain (engine-dependent support).
  140. For example, the query `:zh-CN 大模型 排行榜` searches in Chinese regardless of
  141. the profile's `language`, and `!github compose network mapping` uses only the
  142. GitHub engine. Verify engine names against your instance's engine list.
  143. If several DSH search providers are available, select this one with
  144. `DSH_WEB_SEARCH_PROVIDER=searxng` or the corresponding `searchProvider` DSH web configuration.
  145. ## Troubleshooting
  146. - `E_DOCKER_MISSING` / `E_DOCKER_OFFLINE`: install or start Docker.
  147. - `E_COMPOSE_UNSUPPORTED`: enable Docker Compose v2.
  148. - `E_JSON_DISABLED`: add `json` to SearXNG `search.formats`.
  149. - `E_AUTH_FAILED`: check the external instance's `authHeader` configuration.
  150. - `E_TLS_FAILED`: the endpoint's TLS certificate failed validation; check the certificate chain
  151. and retry.
  152. - `E_RATE_LIMITED`: adjust the instance limiter or upstream engine selection.
  153. - `E_RESOURCE_FOREIGN`: a same-name Docker resource does not carry this installation's ownership
  154. labels; it is never modified automatically.
  155. - `E_BUNDLE_DAMAGED`: the generated configuration bundle is incomplete or mismatched; `repair`
  156. rebuilds it from the packaged assets while preserving the existing secret.
  157. - `E_DEPLOYMENT_UNSUPPORTED`: the packaged deployment catalog cannot satisfy the request (unknown
  158. or same version requested, or an entry incompatible with the current state); upgrade
  159. dsh-searxng or choose an available version.
  160. - `E_PROFILE_CONCURRENT_MODIFICATION`: the DSH profile changed during the operation; review it and
  161. retry.
  162. `doctor --json` returns the complete redacted check list and actionable error codes.
  163. ## Runtime support
  164. - Node.js: 20 and newer.
  165. - CLI, tests, build, and packed artifact: verified on Linux, macOS, and Windows in CI.
  166. - Managed Docker journey (including repair and update rollback) and Docker adapter integration:
  167. verified in opt-in Linux CI with Docker Engine and Compose v2. The release certification runner
  168. is also exercised there; CI provides no Docker Desktop and uses a stub `dsh`, so it is not a
  169. formal certification.
  170. - **Certified** Docker environments per release: only those with a complete passing report from
  171. the release tarball in [docs/release-certification.md](docs/release-certification.md) — one
  172. each from macOS + Docker Desktop, Windows + Docker Desktop + WSL2, and Linux + Docker Engine +
  173. Compose v2.
  174. - Docker Desktop on macOS is certified for `0.4.0`
  175. (`docs/certification/v0.4.0-darwin-arm64.json`); Docker Desktop on Windows is compatible (same
  176. engine, same Compose v2 plugin) but uncertified until its report exists for a given release.
  177. - External SearXNG mode does not require Docker and works on any platform with Node.js 20+.
  178. - Podman and Podman Compose are not supported in the managed path.
  179. `setup` selects the deployment to install from the packaged deployment catalog
  180. (newest entry compatible with the current state schema) and reuses a healthy
  181. existing deployment that is still listed in the catalog; use `update` to move
  182. between deployment versions.
  183. dsh is in developer preview with breaking changes expected. Version 0.4.0 supports
  184. `@deepseek-ai/dsh-web >=0.1.0-rc.6 <0.2.0` and
  185. `@deepseek-ai/dsh-launch-environment >=0.0.1-rc.3 <0.2.0`.
  186. ## Development
  187. ```sh
  188. pnpm install
  189. pnpm verify
  190. ```
  191. The repository Docker example is development-only. The packaged setup path is the supported
  192. quickstart because it pins the image, generates a private secret, labels every owned resource, and
  193. validates the final provider before activation. The opt-in Linux CI job runs both real Docker
  194. release checks:
  195. ```sh
  196. DSH_SEARXNG_E2E=1 pnpm test:e2e
  197. DSH_SEARXNG_DOCKER_INTEGRATION=1 pnpm test -- test/cli/docker.integration.test.ts
  198. ```
  199. Platform certification of a packed tarball runs on each release host:
  200. ```sh
  201. pnpm pack --pack-destination ./node_modules/.cache/pack
  202. pnpm certify:platform -- --tarball ./node_modules/.cache/pack/dsh-searxng-<version>.tgz
  203. ```
  204. ## License
  205. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.