dsh-web-search-searxng

A standalone SearXNG-backed web search provider for the DeepSeek Harness web profile. It plugs into the harness's web-search seam (ctx.web), so the agent's web_search tool searches through your own self-hosted SearXNG instance instead of a vendor API.

• Plain ESM, no build step.
• Ships as a bundle: one dsh plugin command installs and activates it automatically.
• Single configuration knob: $SEARXNG_BASE_URL.
• Tested (pnpm test, 20 tests, vitest).

The one-command install

From a fresh DeepSeek Harness checkout (or with dsh on PATH):

dsh plugin --profile web add /path/to/dsh-web-search-searxng

That's it. The plugin is automatically appended to the web profile's bundle stack and its patch layer (shipped in this repo as cordis.patch.yml):

• switches the web seam to this provider (searchProvider: searxng), and
• mounts the plugin row.

No cordis.patch.yml hand-editing. No rebuild.

Configure: set one environment variable

Your SearXNG address is read from SEARXNG_BASE_URL (defaults to http://localhost:8888):

export SEARXNG_BASE_URL=http://192.168.30.74:8888   # your instance

Optional knobs:

Variable	Default	Meaning
SEARXNG_BASE_URL	http://localhost:8888	Your SearXNG instance; /search is appended.
SEARXNG_NUM_RESULTS	10	Default result count when a request doesn't specify its own bound.
SEARXNG_API_KEY	(none)	Optional, for instances behind a key.

Then start (or restart) dsh web in that shell — or add the exports to your shell profile / the .env the harness loads.

No environment variables? Then edit the one line in the bundle's cordis.patch.yml:

baseURL: !!js process.env.SEARXNG_BASE_URL ?? 'http://localhost:8888'
#                                      ^^^^^^^^^^^^^^^^^ change this default

Both ways produce the same result — the choice is yours.

Verify

web_search("postgresql vs mysql")

should return aggregated results from your instance.

Wait — will I get the Settings → Plugins card?

Only after applying two small harness-side changes (the card lives in the harness source itself, and an allowlist gate in api-proxy.ts must name this namespace). They're documented at the end of this README in Make the Settings card work. The search itself works without them.

---

Details

Files

dsh-web-search-searxng/
├── cordis.patch.yml     # bundle layer: activation + config (env-first)
├── src/
│   ├── index.js         # plugin entry: registers provider + settings section
│   └── provider.js      # SearXNG JSON API client (GET /search?format=json)
├── tests/provider.spec.js
├── package.json         # declares dsh.bundle → auto layer on `dsh plugin add`
├── README.md
└── LICENSE

How the one command works

dsh plugin --profile web add runs pnpm add inside the profile directory, then reconciles the bundle list: any installed package declaring dsh.bundle in its package.json is appended to dsh.profile.bundles (harness apps/cli/src/plugin.ts, reconcilePlugins). This repo's package.json declares exactly that, pointing at cordis.patch.yml, which is applied as the top layer over the base/web-app bundles.

Options at a glance

Setting	Default	Via
baseURL	http://localhost:8888	$SEARXNG_BASE_URL env, or the patch line
numResults	10	$SEARXNG_NUM_RESULTS env, or the patch line
apiKey	(none)	$SEARXNG_API_KEY env, or the patch line

The plugin also exposes a web-search-searxng settings section, so once the Settings card is enabled (below) those same fields become editable in the GUI and writes apply to the next search immediately.

Running tests locally

mkdir -p node_modules/@deepseek-ai   # dev-only: link peers from a harness profile
for p in cordis dsh-invariants dsh-launch-environment dsh-settings dsh-web schemastery; do
  ln -sf "$DSH_HOME/profiles/node_modules/@deepseek-ai/$p" "node_modules/@deepseek-ai/$p"
done
pnpm test

node_modules/ is git-ignored.

---

Make the Settings card work (optional)

The editable card needs two changes inside the harness (they can't ship from a host-only plugin, because the browser bundle of ui-settings-plugins and the settings exposure gate are part of the harness). Both are small:

1. Expose the namespace — in the harness, edit packages/host/apiproxy/src/api-proxy.ts:

const WEB_SETTINGS_NAMESPACES = [
  'agent-loop', 'shell', 'locale', 'permission', 'ui-conversation', 'ui-theme',
  'web-search-deepseek', 'web-search-searxng',   // ← add this
] as const

2. Render the card — in packages/client/ui-settings-plugins, add SearxngCard/SearxngCardController (endpoint + default result count), register it in index.ts (settings.plugin.item slot), add the searxng* locale keys, then rebuild the web artifacts (pnpm run build:lib:host + pnpm run build:lib:client + build:web) and restart the GUI.

Without these two, everything works except the in-UI editor: search is live, config via env var or the patch file. With them, you also get Settings → Plugins → Web search (SearXNG).

---

Created with the DeepSeek Harness and DeepSeek V4 Flash 0731 running on 2 × Asus Ascent GX10.