@deads-inc/dsh-web-search-brave
Brave Search API-backed web search provider for DeepSeek Harness (dsh). It registers a WebSearchProvider into the ctx.web seam, so the built-in web_search tool works out of the box when you have a Brave Search API key.
- MIT license, ~270 lines of code, zero runtime dependencies
- Concurrency-safe rate limiting (1500ms gap between requests)
- Exponential backoff with jitter on 429s
- Configurable via DSH Settings or env vars
Install
Requires BRAVE_API_KEY from brave.com/search/api.
From npm (recommended):
dsh plugin --profile web add @deads-inc/dsh-web-search-brave
export BRAVE_API_KEY=<your-key>
From this repo:
git clone https://github.com/ChrisDeadman/dsh-web-search-brave.git
cd dsh-web-search-brave
export BRAVE_API_KEY=<your-key>
bash install.sh
Restart dsh web. Verify the provider is active:
dsh --profile web --dump-config | grep -A3 brave
How it works
- Registers the
brave-search provider on the ctx.web seam.
- Resolves the API key in this order:
- Literal
apiKey in the config (not recommended).
- The
BRAVE_API_KEY credential stored in the DSH credentials service.
- The
BRAVE_API_KEY env var at launch time.
- Serializes concurrent calls through an in-process rate limiter (1500ms gap, configurable).
- On 429/403, honors
Retry-After, backs off with exponential + jittered backoff (capped at 30s), up to 3 attempts.
Configuration
All options are optional; sensible defaults are used.
| Option | Env / Config Key | Default | Notes |
|---|
| API key | BRAVE_API_KEY | — | Required. |
| API base URL | BRAVE_SEARCH_BASE_URL | https://api.search.brave.com/res/v1/web/search | Override for proxies or testing. |
| Throttle (ms) | — | 1500 | Min gap between outbound requests. |
| Max attempts | — | 3 | Retries on 429/403 before failing. |
Enabling as the active search provider
The plugin registers brave-search but does not forcibly enable it. To use it as your search backend, add this to your profile's cordis.patch.yml:
- id: web
config:
searchProvider: brave-search
bash install.sh does this automatically for you.
Security notes
- Your
BRAVE_API_KEY is only ever sent to the configured baseURL (default: Brave's official endpoint).
- Custom
baseURL is an escape hatch for proxies or testing; use it deliberately. The plugin does not validate the URL's domain.
- There are no postinstall scripts, no network calls other than the search API, no telemetry.
Development
This package is plain ESM with no build step and no runtime dependencies —
everything it imports (@deepseek-ai/*) is provided by the host DSH install
as peer dependencies.
To test a local change, run bash install.sh, then in a fresh terminal:
# 1. Confirm the bundle is wired into the composed profile config:
dsh --profile web --dump-config | grep -A3 brave
# 2. (Optional) Import the module directly. This needs the profile's
# node_modules to already carry the @deepseek-ai/* peers (a web profile
# that has any dshmarket package does). It fails harmlessly otherwise —
# dsh itself always resolves the peers from its own installation at boot:
node --input-type=module -e "
const m = await import('@deads-inc/dsh-web-search-brave');
if (typeof m.apply !== 'function' || m.name !== 'web-search-brave') throw new Error('bad module');
console.log('OK: exports:', Object.keys(m).join(', '));
"
# 3. With BRAVE_API_KEY set, run a real end-to-end search:
dsh --profile web "Use web_search to find one page about Node.js 24. Reply with just the URL."
See AGENTS.md for guidance for AI coding agents working on this repo.
License
MIT.
