Brave Search Plugin

Web search using the Brave Search API — a fast, privacy-focused alternative to Google.

Installation

Install this tool individually:

beige tools install github:matthias-hausberger/beige-toolkit/tools/brave-search

Or install all tools from the toolkit:

# From npm
beige tools install npm:@matthias-hausberger/beige-toolkit

# From GitHub
beige tools install github:matthias-hausberger/beige-toolkit

Configuration

Key	Default	Description
apiKey	(none)	Brave Search API key. Get one at brave.com/search/api. Falls back to BRAVE_API_KEY environment variable if not set in config.
maxResults	10	Default number of results to return (1–20).
timeoutSeconds	30	HTTP request timeout in seconds.

Prerequisites

Requirement	Details
Brave Search API key	Create an account at brave.com/search/api and generate a key. Free tier covers ~2,000 queries/month.

Config Examples

Basic setup with API key:

{
  tools: {
    "brave-search": {
      "config": {
        "apiKey": "BSA_your_api_key_here",
      },
    },
  },
}

Using environment variable:

export BRAVE_API_KEY="BSA_your_api_key_here"

No apiKey in config needed — the plugin picks up BRAVE_API_KEY automatically.

Custom result count and timeout:

{
  tools: {
    "brave-search": {
      "config": {
        "apiKey": "BSA_your_api_key_here",
        "maxResults": 5,
        "timeoutSeconds": 20,
      },
    },
  },
}

Usage

The plugin provides a brave-search tool with a single search subcommand:

brave-search search <query>
brave-search search <query> --count <n>
brave-search search <query> --country <code>
brave-search search <query> --offset <n>

Examples:

# Basic search
brave-search search "cloudflare workers documentation"

# Limit to 3 results
brave-search search "typescript best practices" --count 3

# German-language results
brave-search search "nachrichten heute" --country DE

# Pagination (skip first 10 results)
brave-search search "rust programming" --offset 10

Output Format

Results are returned as a numbered list with title, URL, snippet, and age:

Search results for: cloudflare workers

1. Cloudflare Workers Documentation
   https://developers.cloudflare.com/workers/
   Build serverless applications with Cloudflare Workers. Run JavaScript and...

2. What are Cloudflare Workers?
   https://www.cloudflare.com/learning/serverless/what-is-cloudflare-workers/
   Cloudflare Workers is a serverless platform that allows you to deploy...

3. Getting Started with Workers
   https://developers.cloudflare.com/workers/get-started-guide/
   This guide walks you through creating and deploying your first Cloudflare...
   2 days ago

Command Reference

Command	Description
search <query>	Search the web. Required.
--count <n>	Number of results to return (1–20). Overrides the config default.
--country <code>	2-letter country code for region-specific results (e.g., US, DE, GB). Case-insensitive.
--offset <n>	Pagination: skip first N results. Useful for loading more pages.

Tool name: brave-search

Error Reference

Error	Cause
Brave Search API key not configured	No apiKey in config and no BRAVE_API_KEY environment variable set.
Brave Search API error 401	Invalid API key. Verify your key at brave.com/search/api.
Brave Search API error 429	Rate limit exceeded. Upgrade your plan or wait for quota reset.
Search failed: network error	Network connectivity issue or request timeout.

Implementation Details

• Target: Sandbox (runs inside the agent container)
• API: GET https://api.search.brave.com/res/v1/web/search
• Auth: X-Subscription-Token header
• Timeout: Configurable, defaults to 30 seconds
• Rate limits: Enforced by Brave based on your plan; the plugin does not cache results

API Limits

Brave Search API is rate-limited by plan:

Plan	Queries/month
Free	~2,000
Search	$5/month for 1,000 queries (includes$5 credit)

Monitor usage at brave.com/search/api to avoid unexpected charges.

Privacy

Brave Search is privacy-focused:

• No user tracking
• No personal data retention
• Queries sent directly to Brave’s API
• No search history stored by the plugin