Foreword¶

In the plugin architecture of DSH, web search can be integrated into external backends via the ctx.web capability. dsh-searxng provides a path based on SearXNG: using a free, self-hosted, API-key-free metasearch instance to provide web_search to the agent. The community directory is an independent site and is not equivalent to the official app store. Below is an introduction to its positioning, installation method, and common operations.

What is this¶

dsh-searxng is a DSH plugin maintained by rogerdigital, licensed under MIT, version 0.2.1. It registers a SearXNG-backed search provider to DSH’s web capability seam (ctx.web), allowing the agent to perform web search via SearXNG.

It is aimed at developers who need to enable web search in DSH but wish to use a self-hosted SearXNG instance. dsh itself is in developer preview, so breaking changes may occur later.

Core Features¶

• Registers a SearXNG-backed search provider to ctx.web.
• setup creates loopback-only, pinned SearXNG Docker deployments; activates the profile only after the JSON API and search check pass.
• Supports using existing local, remote, authenticated, or independently managed SearXNG instances via --url; the external mode does not start Docker.
• Supports selecting profile and port in the setup command.
• Provides status, doctor, remove operations, and supports --service and --purge-data options.
• Supports provider configuration keys: baseURL, language, engines, categories, authHeader.
• When multiple search providers are available, use DSH_WEB_SEARCH_PROVIDER=searxng or the corresponding searchProvider DSH web config to select it.
• Requires Node.js 20 or later.
• Managed Docker path requires Docker Engine or Docker Desktop, and Docker Compose v2; Podman and Podman Compose are not supported.

Installation and Activation¶

First, confirm the environment: Node.js 20 or later; if using the managed Docker path, you also need Docker Engine or Docker Desktop, and Docker Compose v2.

Quick connection using setup¶

Execute setup first to let the plugin complete the deployment and checks; then use DSH via the corresponding profile.

npx dsh-searxng setup
dsh --profile web

setup creates loopback-only, pinned SearXNG Docker deployments, waits for the JSON API, and performs a search check under the SearXNG and final DSH provider configuration; the profile is activated only after passing.

After the above steps, the search provider can be used in the web profile.

If you need to use another profile or port:

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

Using an existing SearXNG instance¶

If you already have a local, remote, authenticated, or independently managed SearXNG instance, you can specify the endpoint directly:

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

The external endpoint must satisfy: HTTP(S), no credentials, no query, no fragment, and enable JSON search. The external mode will not invoke Docker.

Installing only the plugin package¶

If you manage DSH profile configurations yourself and don’t want setup to automatically attach configuration, you can install the plugin package only:

dsh plugin add dsh-searxng

Use under a named profile:

dsh plugin --profile <name> add dsh-searxng

Typical Usage¶

Check status¶

Status check:

npx dsh-searxng status --profile web

More complete check:

npx dsh-searxng doctor --profile web

Remove plugin¶

Basic removal:

npx dsh-searxng remove --profile web

If you need to synchronously process the managed service, use:

npx dsh-searxng remove --profile web --service

If you need to permanently delete managed data, use:

npx dsh-searxng remove --profile web --service --purge-data

Permanent deletion prompts for confirmation in an interactive terminal; automation requires adding --yes. Destructive Docker operations are only executed when container, network, and volume labels match the current DSH home; foreign resources with the same name will be rejected.

Provider configuration¶

setup manages the web-search-searxng row in the DSH profile. Optional values can be added to this row:

If multiple DSH search providers exist, select this provider:

DSH_WEB_SEARCH_PROVIDER=searxng

Or use the corresponding searchProvider DSH web configuration.

Use Cases and Notes¶

It is suitable for the following situations:

• Want to provide web search to DSH agents but prefer metasearch like SearXNG.
• Want self-hosted, free, and key-free.
• Already have a SearXNG instance and don’t want the plugin to manage Docker.
• Need to distinguish multiple search environments by profile and port.

Pre-use notes:

• Node.js 20 or later is required.
• Managed Docker path requires Docker Engine or Docker Desktop, and Docker Compose v2; Podman and Podman Compose are not supported.
• Docker Desktop on macOS and Windows is supported but has not completed formal release certification.
• dsh is in developer preview, so breaking changes may appear upstream.
• The plugin runs in the current DSH environment and uses the permissions of the current DSH process to access Docker, files, and network. You should check the source code, command behavior, and MIT license before installing.
• --purge-data is a destructive operation, intended only for scenarios where you confirm that managed resources belong to the current DSH home.

Conclusion¶

The value of dsh-searxng lies in providing a SearXNG-based search path to DSH’s ctx.web: it can create managed Docker instances via the plugin, or reuse existing SearXNG endpoints. If you are configuring web search for an agent, you can start with setup and then check the final status using status and doctor.

Related links:

• GitHub: https://github.com/rogerdigital/dsh-searxng
• Community directory page (for reference): https://www.skillhub.cn/plugins/rogerdigital/dsh-searxng