dsh-searxng

dsh plugin --profile web add dsh-searxng

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.
• 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.

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:

Key · Default · Meaning

baseURL · managed or --url endpoint · SearXNG base URL.

language · none · SearXNG language, for example zh-CN or en-US.

engines · none · Comma-separated engine allowlist.

categories · none · Comma-separated category filter.

authHeader · none · Authorization header for a protected external instance.

cacheTtlMs · 600000 · Cached query result lifetime in milliseconds; 0 disables caching.

minIntervalMs · 1500 · Minimum spacing between network requests; 0 disables pacing.

queueCapacity · 8 · Requests that may wait for a pacing slot before the provider rejects with backpressure.

totalBudgetMs · 15000 · Wall-clock budget for one search call, spanning pacing wait, backoff, and network attempts.

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

…(truncated)