dsh-searxng

A DeepSeek Harness (dsh) plugin that registers a SearXNG-backed search provider into the web capability seam (ctx.web), giving your agent web_search through a free, self-hosted, key-less metasearch instance — instead of the paid Exa/Perplexity APIs.

Quick start

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.

Existing SearXNG

An existing local, remote, authenticated, or independently managed SearXNG instance is a first-class path:

npx dsh-searxng setup --profile web --url https://search.example.com

The endpoint must be HTTP(S), contain no credentials, query, or fragment, and enable JSON search. Existing provider options such as authHeader, language, engines, and categories in the DSH profile are preserved and used by validation. External mode never invokes Docker.

Manual plugin installation

If you manage the DSH profile patch yourself and do not want the setup command to attach it, install only the plugin package:

dsh plugin add dsh-searxng

With a named profile, use dsh plugin --profile <name> add dsh-searxng.

Operations

# Fast health result; stops at the first failure.
npx dsh-searxng status --profile web

# Ordered environment, Docker, ownership, HTTP, JSON, search, profile, and provider checks,
# plus the local privacy posture with its explicit out-of-scope limits.
npx dsh-searxng doctor --profile web

# Read-only engine-health probe battery: per-engine reported failures with reasons,
# result contribution, and evidence limits. Writes nothing.
npx dsh-searxng tune --profile web

# Plan and execute ownership-safe repairs for the managed deployment.
npx dsh-searxng repair --profile web

# Move the managed deployment to a packaged version with verified rollback.
npx dsh-searxng update --profile web

# Detach the profile and remove the plugin package from that profile.
npx dsh-searxng remove --profile web

# Also stop and remove the owned service; keep its data and local state.
npx dsh-searxng remove --profile web --service

# Permanently delete the exact owned data volume and managed directory.
npx dsh-searxng remove --profile web --service --purge-data

Permanent deletion prompts on an interactive terminal. Automation must add --yes. --json is available on setup, status, doctor, repair, update, and remove. Destructive Docker operations run only after the container, network, and volume labels match this DSH home; same-name foreign resources are refused.

Recovery semantics

repair and update journal their progress under $DSH_HOME/dsh-searxng/journal.json between the first mutation and validated completion; setup and remove read that journal to refuse during or clean up after an interruption.

• setup refuses to run while an interrupted operation is recorded and points at repair. When a matching deployment is recorded but unhealthy, it restarts a wedged runtime, or — if the container is gone while the recorded bundle survives (the leftover of remove --service without --purge-data, or a manual docker compose down) — recreates the runtime from that bundle.
• repair takes over when a journal exists: it recomputes the recovery decision from disk (clear the journal, validate the target, or resume the rollback) before any ordinary repair, and also removes quarantined stale locks left by dead processes. doctor reports the interrupted operation's id, kind, phase, and age.
• update is transactional: the current deployment stays authoritative until the target passes readiness, real-search, and provider validation. Any failure after the first Docker mutation rolls back to the previous image and configuration and revalidates them; same-version updates are rejected with E_DEPLOYMENT_UNSUPPORTED.
• remove --service clears the journal once the deployment is gone, so a subsequent setup is not refused. It also removes the labeled leftovers of a container-less deployment by deriving the compose file from the bundle recorded in state.

Provider configuration

The setup command manages the web-search-searxng row in $DSH_HOME/profiles/<name>/cordis.patch.yml. These optional values can be added to that row:

Repeated queries are served from an in-process cache scoped to the provider instance (nothing is written to disk); a cache hit performs no network request. Concurrent searches pass a token bucket (burst 2, then one request per minIntervalMs), and a full queue rejects immediately with a retryable error instead of holding the caller. Failed responses and empty result pages are never cached — a cached empty page would mask upstream recovery for the whole TTL — and an empty result page is returned as-is: the engines/categories allowlist is never silently widened to chase results. When the instance answers HTTP 429, the provider honors Retry-After and retries at most once within the remaining budget.

Multi-instance failover

List two or more endpoints in baseURLs (at most 8, duplicates collapse) to route searches across them — for example a local managed instance first and a remote one second:

web-search-searxng:
  baseURLs:
    - http://127.0.0.1:8080
    - https://searxng.example.net

The first entry is primary. When an attempt fails with a network error, a timeout, or HTTP 502/503/504/429, the endpoint's health penalty rises and the next attempt (and the first attempt of later searches) goes to the healthiest endpoint; penalties decay with a 30 s half-life, so the primary recovers the first slot about a minute after its last failure, or immediately after a successful search. Malformed responses (contract failures) and other 4xx statuses never fail over — those are configuration problems on that endpoint that switching would silently mask. The cache is keyed by the whole pool, the pacing bucket is per endpoint, and the totalBudgetMs deadline spans every endpoint's attempts; empty result pages are valid answers and never trigger failover. setup --url still records a single external endpoint per profile — configuring a pool is a manual profile-config edit until the CLI follow-up ships.

Per-query controls

SearXNG supports per-query routing inside the query string itself; the provider passes query syntax through untouched:

• :zh-CN / :en — select the result language for this query (: prefix).
• !bing / !news — select one engine or category for this query (! prefix).
• site:example.com — restrict results to one domain (engine-dependent support).

For example, the query :zh-CN 大模型 排行榜 searches in Chinese regardless of the profile's language, and !github compose network mapping uses only the GitHub engine. Verify engine names against your instance's engine list.

If several DSH search providers are available, select this one with DSH_WEB_SEARCH_PROVIDER=searxng or the corresponding searchProvider DSH web configuration.

Troubleshooting

• E_DOCKER_MISSING / E_DOCKER_OFFLINE: install or start Docker.
• E_COMPOSE_UNSUPPORTED: enable Docker Compose v2.
• E_JSON_DISABLED: add json to SearXNG search.formats.
• E_AUTH_FAILED: check the external instance's authHeader configuration.
• E_TLS_FAILED: the endpoint's TLS certificate failed validation; check the certificate chain and retry.
• E_RATE_LIMITED: adjust the instance limiter or upstream engine selection.
• E_RESOURCE_FOREIGN: a same-name Docker resource does not carry this installation's ownership labels; it is never modified automatically.
• E_BUNDLE_DAMAGED: the generated configuration bundle is incomplete or mismatched; repair rebuilds it from the packaged assets while preserving the existing secret.
• E_DEPLOYMENT_UNSUPPORTED: the packaged deployment catalog cannot satisfy the request (unknown or same version requested, or an entry incompatible with the current state); upgrade dsh-searxng or choose an available version.
• E_PROFILE_CONCURRENT_MODIFICATION: the DSH profile changed during the operation; review it and retry.

doctor --json returns the complete redacted check list and actionable error codes.

Runtime support

• Node.js: 20 and newer.
• CLI, tests, build, and packed artifact: verified on Linux, macOS, and Windows in CI.
• Managed Docker journey (including repair and update rollback) and Docker adapter integration: verified in opt-in Linux CI with Docker Engine and Compose v2. The release certification runner is also exercised there; CI provides no Docker Desktop and uses a stub dsh, so it is not a formal certification.
• Certified Docker environments per release: only those with a complete passing report from the release tarball in docs/release-certification.md — one each from macOS + Docker Desktop, Windows + Docker Desktop + WSL2, and Linux + Docker Engine + Compose v2.
• Docker Desktop on macOS is certified for 0.4.0 (docs/certification/v0.4.0-darwin-arm64.json); Docker Desktop on Windows is compatible (same engine, same Compose v2 plugin) but uncertified until its report exists for a given release.
• External SearXNG mode does not require Docker and works on any platform with Node.js 20+.
• Podman and Podman Compose are not supported in the managed path.

setup selects the deployment to install from the packaged deployment catalog (newest entry compatible with the current state schema) and reuses a healthy existing deployment that is still listed in the catalog; use update to move between deployment versions.

dsh is in developer preview with breaking changes expected. Version 0.4.0 supports @deepseek-ai/dsh-web >=0.1.0-rc.6 <0.2.0 and @deepseek-ai/dsh-launch-environment >=0.0.1-rc.3 <0.2.0.

Development

pnpm install
pnpm verify

The repository Docker example is development-only. The packaged setup path is the supported quickstart because it pins the image, generates a private secret, labels every owned resource, and validates the final provider before activation. The opt-in Linux CI job runs both real Docker release checks:

DSH_SEARXNG_E2E=1 pnpm test:e2e
DSH_SEARXNG_DOCKER_INTEGRATION=1 pnpm test -- test/cli/docker.integration.test.ts

Platform certification of a packed tarball runs on each release host:

pnpm pack --pack-destination ./node_modules/.cache/pack
pnpm certify:platform -- --tarball ./node_modules/.cache/pack/dsh-searxng-<version>.tgz

License

MIT