Preface¶

DSH’s ctx.web provides a web capability seam. When connecting search to an agent, the provider implementation directly affects search costs and operational boundaries. Unlike issuing a complete Messages request, dsh-web-search-searxng directs searches to a self-hosted SearXNG instance’s /search?format=json endpoint: searches require no API key, and each search does not consume a model turn.

DSH’s plugin ecosystem emphasizes “everything is a plugin.” This introduces a community-maintained plugin, not an official application store entry.

What This Is¶

dsh-web-search-searxng is a DSH plugin maintained by chinng-inta, licensed under MIT. It is based on SearXNG and registers a WebSearchProvider for DeepSeek Harness’s ctx.web.

This plugin does not register a model-facing tool. The web_search tool, schema, prompt guidance, and result cards are provided by @deepseek-ai/dsh-tool-web. After installing dsh-web-search-searxng, it enables the existing web_search tool to use your own SearXNG instance.

Core Features¶

• Registers a SearXNG-based WebSearchProvider for ctx.web.
• Queries via the SearXNG instance’s /search?format=json endpoint instead of issuing a complete Messages request.
• Requires no API key for searches, and each search does not consume a model turn.
• Maps SearXNG results and answers to the seam’s sources and content, deduplicating by URL.
• Supports optional configuration: baseURL, categories, engines, language, timeRange, safesearch, timeoutMs, maxSnippetChars, headers.
• Falls back to $SEARXNG_URL when baseURL is not set.
• Configuration is projected per search; modifying the settings document takes effect on the next search.

Installation and Enablement¶

Install from npm¶

dsh plugin --profile web add dsh-web-search-searxng

Install from Repository¶

dsh plugin --profile web add github:chinng-inta/dsh-web-search-searxng

When installing from a git repository, pnpm will block install scripts. The first installation will fail and print the allowBuilds key that needs to be allowed. This key is pinned to a commit SHA and must be updated after installing a new revision. Example:

allowBuilds:
  "dsh-web-search-searxng@https://codeload.github.com/chinng-inta/dsh-web-search-searxng/tar.gz/<commit-sha>": true

Point to a SearXNG Instance¶

export SEARXNG_URL=http://searxng.internal:8888

Verify the Combination¶

Before starting, you can check the configuration combination:

dsh --profile web --dump-config | grep -A3 'id: web'

Enable the SearXNG JSON Endpoint¶

SearXNG does not enable the JSON API by default. You need to include json in search.formats within the instance’s settings.yml:

search:
  formats:
    - html
    - json

Typical Usage¶

The plugin owns the web-search-searxng configuration namespace. Below is an example of a user-level settings document:

web-search-searxng:
  language: ja
  maxSnippetChars: 300

All configuration keys are optional. baseURL falls back to $SEARXNG_URL when not set. Configuration is projected per search; modifying the settings document takes effect on the next search.

timeoutMs is the provider’s search resource limit, not a model-facing tool-call budget. The model-side budget is controlled by @deepseek-ai/dsh-tool-call-timeout-policy via tool-web’s searchTimeoutMs. Keeping timeoutMs below the tool budget allows a slow instance to manifest as a provider-side failure rather than a tool timeout.

maxResults is not pushed down to SearXNG. After SearXNG returns the full first page, truncation is performed by the seam.

Mapping and Runtime Behavior¶

The plugin maps SearXNG results and answers to the seam’s sources and content, deduplicating by URL.

The provider rejects redirects, configured as:

redirect: 'error'

available() only performs a local, synchronous check for a parseable http(s) base URL and does not access the network.

Provider Selection¶

The plugin sets the following via a bundle patch:

web.searchProvider: searxng

If multiple providers are available and none is specified, the search fails with:

WEB_PROVIDER_AMBIGUOUS

Applicable Scenarios and Considerations¶

Suitable for teams that already have or plan to run a self-hosted SearXNG instance. Public SearXNG instances may reject programmatic access, such as returning HTTP 403 through bot filters, or may impose strict rate limits. The README recommends running your own instance.

The plugin runs with the permissions of the current dsh process. Review the source code and license before installation. This plugin is licensed under MIT.

Conclusion¶

The value of dsh-web-search-searxng lies in connecting DSH’s web search to a self-hosted SearXNG instance: searches require no API key, each search does not consume a model turn, while retaining the tool surface provided by @deepseek-ai/dsh-tool-web. It is suitable for agent deployments requiring a self-controllable, auditable search backend.

Confirmed repository address:

https://github.com/chinng-inta/dsh-web-search-searxng