Web search #

Adds a web_search tool. Returns a title, URL, and snippet for each result. Every result is cited under the reply.

Configuration #

Add the plugin under Admin > Plugins and fill in its options. The API key is stored encrypted.

Option	Default	Meaning
engine	Required	The site-wide engine. See Engines.
apiKey		The site-wide engine's key. Required for engines that need one.
baseURL		The site-wide SearXNG instance. Required for SearXNG.
adminEngineRoles	[user]	List of roles allowed to use the admin-configured search engine.
enabledByDefault	false	Whether search is on for users who haven't switched it themselves.
userToggle	true	Whether users can switch search on and off in their settings.
userEngines	true	Whether users can pick their own engine and key. Set to false to use the site-wide engine for everyone.
maxResults	5	Results per search, from 1 to 20.

Engines #

Engine	engine	Needs	Notes
Tavily	tavily	apiKey	Currently offers 1,000 free searches a month. Sign up at tavily.com.
Brave	brave	apiKey	Currently offers $5 credit per month / roughly 1,000 searches. Signup and more information on Brave Search API.
SearXNG	searxng	baseURL	Free / self-hosted. Instance must allow JSON results: add json to search.formats in its settings.yml.
DuckDuckGo	duckduckgo	Nothing	Scrapes DuckDuckGo's HTML results, as there's currently no public search API available.
Kagi	kagi	apiKey	Requires an API account. More info on their API page.

User settings #

If userEngines is enabled end users can configure their own search engine in Settings > Plugins:

• default uses the admin-configured engine.
• Any other engine uses the user's own key, or base URL for SearXNG.

Adding an engine #

1. Add a file per search engine under src/engines/, it needs to build the request and parse the response.
2. Add that file to the list in src/engines/index.ts.

Shared code in src/search.ts handles request sending, errors, timeouts, and result cleanup.

See src/engines/brave.ts for a small example.