BroClaw Guide

📖 User Guide

BroClaw is a 100% browser-native AI agent studio — no server, no backend, no account required. Your API keys and files never leave your machine.

Quick Start (30 seconds)

1. Open the app — click Open BroClaw on the landing page.
2. Pick a workspace — choose a local folder (recommended) or use Memory Mode for a session-only scratch space.
3. Select a model — click the model chip in the top-left corner. Use a free local model (no key needed) or paste an API key for cloud quality.
4. Type a task — e.g. "Research the latest in AI and write a report" or "Build a todo app in HTML/CSS/JS".
5. Watch it work — BroClaw searches the web, reads pages, writes files, and iterates until the job is done.
6. Stop anytime — click ⏹ in the chat input to immediately halt the agent.

Core Concepts

Agent Loop

BroClaw uses a Think → Act → Observe cycle. The AI reasons about what to do next, executes an action (search, read, write), feeds the result back to itself, and repeats until the task is complete or you stop it.

Workspace Folder

A local folder you grant BroClaw access to. Config, skills, and generated files are saved here. You own the folder — BroClaw writes nothing outside it.

Memory Mode

No folder needed. Everything lives in-session only in IndexedDB. Files the agent creates aren't saved to disk after you close the tab.

Skills

Pre-built prompt accelerators for common tasks. Pick a skill, fill in the variable, and send — no need to write the full prompt yourself.

MCP Server

An external tool provider speaking the Model Context Protocol. Add one in Settings → Connectors and its tools become available to the agent automatically — see MCP Servers above.

Extended Thinking

When using Claude or o3/o4-mini models, BroClaw streams the model's internal reasoning steps in real time so you can follow its logic step by step.

Supported Models

Privacy & Security

• 🔑 API keys are AES-GCM 256-bit encrypted in localStorage — never stored in plain text, never sent to BroClaw servers.
• 🌐 All AI calls go directly from your browser to the provider (Anthropic, OpenAI, etc.) — BroClaw has no backend to intercept them.
• 💾 Chat history is stored locally in IndexedDB inside your browser — it never leaves your machine unless you explicitly export it.
• 🚫 No telemetry beyond an anonymous visit count (opt-in via cookie banner). No user accounts, no session tracking.

Keyboard Shortcuts

🦙 Connecting Ollama to BroClaw

Ollama lets you run powerful AI models (Qwen3, Llama, Phi-4, Mistral…) locally on your own hardware — completely free, completely private. BroClaw connects to it directly from the browser over http://localhost:11434.

Step 1 — Install Ollama

If you haven't already, download and install Ollama from ollama.com ↗. It runs on Windows, macOS, and Linux.

Step 2 — Start Ollama with the correct CORS setting

You must start Ollama with OLLAMA_ORIGINS=https://broclaw.io. The fastest way is BroClaw's built-in script downloader:

1. Go to Settings → Local / Custom in BroClaw.
2. Click 🪟 Download for Windows (.bat) or 🍎 Download for Mac/Linux (.sh).
3. Run the downloaded script. It sets the CORS origin and starts Ollama automatically.

Or run manually:

Windows (PowerShell)

# Kill any running Ollama (including the tray app)
taskkill /IM ollama.exe /F

# Permanently write the origin to your user environment (survives reboots)
setx OLLAMA_ORIGINS "https://broclaw.io"

# Set it for this session too, then start serving
$env:OLLAMA_ORIGINS="https://broclaw.io"; ollama serve

macOS / Linux (Terminal)

pkill ollama
OLLAMA_ORIGINS=https://broclaw.io ollama serve

To make it permanent on Mac/Linux, add export OLLAMA_ORIGINS=https://broclaw.io to your ~/.zshrc or ~/.bashrc, then restart your shell.

Step 3 — Pull a model

Open a new terminal window and pull one of these recommended models:

Step 4 — Connect in BroClaw

1. Open Settings → Local / Custom.
2. Set the URL to http://127.0.0.1:11434 (or http://localhost:11434).
3. Select your model from the dropdown — BroClaw fetches the list automatically.
4. Click the model chip in the top-left of the chat to confirm the selection.

Why CORS?

Browsers block HTTPS pages from making requests to HTTP endpoints unless the HTTP server explicitly permits it via Access-Control-Allow-Origin headers. OLLAMA_ORIGINS tells Ollama to send those headers for https://broclaw.io, authorising the browser to forward the response. Chrome and Edge do allow HTTPS → localhost as a special case — but only with the correct origin header from Ollama's side.

Troubleshooting

🔍 Search Provider Setup

BroClaw supports three search backends. SearXNG (self-hosted, free) is the recommended choice for privacy and reliability. Brave Search API and SerpAPI are cloud options that require an API key.

Which Provider Should I Use?

Option A — SearXNG + Caddy (Recommended)

SearXNG is a self-hosted meta-search engine that aggregates Google, Bing, DuckDuckGo, and dozens of other engines. No API key. No rate limits. Results stay on your machine. A lightweight Caddy reverse proxy adds the CORS headers your browser requires to talk to it.

Prerequisites: Docker Desktop ↗ installed and running.

How it works

Browser (BroClaw)
    ↓ POST /search?format=json
Caddy :8888  (adds CORS headers)
    ↓ proxies to
SearXNG :8080 (meta-search engine)
    ↓ queries
Google / Bing / DuckDuckGo / etc.

Without Caddy, the browser would block SearXNG's responses due to missing Access-Control-Allow-Origin headers. Caddy injects this header transparently.

The two config files

Both files are already included in the searxng-config/ folder of your BroClaw download — you don't need to create them. They're shown here so you can verify or recreate them if needed.

📄 searxng-config/docker-compose.yaml

services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    volumes:
      - searxng-data:/etc/searxng
    expose:
      - "8080"
    restart: unless-stopped

  caddy:
    image: caddy:latest
    container_name: caddy
    ports:
      - "8888:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    depends_on:
      - searxng
    restart: unless-stopped

volumes:
  searxng-data:

📄 searxng-config/Caddyfile

:80 {
    reverse_proxy searxng:8080

    # Allow BroClaw (and any browser) to read SearXNG responses cross-origin.
    # Without these headers the browser blocks the response even though the
    # request goes through — SearXNG does not add CORS headers itself.
    header Access-Control-Allow-Origin  "*"
    header Access-Control-Allow-Methods "GET, POST, OPTIONS"
    header Access-Control-Allow-Headers "Content-Type, Accept"

    @options method OPTIONS
    respond @options 204
}

Step 1 — Start the Docker stack

Open a terminal in the searxng-config/ folder (included in the BroClaw download — contains docker-compose.yaml and Caddyfile):

# First time or full reset — removes old data:
docker compose down -v

# Start SearXNG + Caddy reverse proxy:
docker compose up -d

# Wait ~10 seconds for SearXNG to boot and write its config

Step 2 — Enable JSON format

BroClaw reads search results as JSON. You must enable this in SearXNG's settings.yml after first boot (the file is generated by SearXNG on startup — editing it before boot causes YAML parse errors).

Docker Desktop (Windows/Mac):

1. Open Docker Desktop → Volumes → searxng-config_searxng-data
2. Browse to etc/searxng/settings.yml and click to edit.

Linux / terminal:

docker exec -it searxng sh
vi /etc/searxng/settings.yml

Find or add the search block and make it read exactly:

search:
  formats:
    - html
    - csv
    - json
    - rss

Step 3 — Restart & verify

docker compose restart searxng

# Verify JSON works (should return JSON, not an error):
curl "http://localhost:8888/search?q=test&format=json"

Step 4 — Connect in BroClaw Settings

1. Go to Settings → Search.
2. Set Provider to SearXNG.
3. Set URL to http://localhost:8888.
4. Use the Test connection button in Settings to confirm it works.

Troubleshooting SearXNG

Why not a public instance? Public instances at searx.space ↗ often disable the JSON format BroClaw needs, enforce rate limits that block repeated agent searches, and may log your queries. Running locally avoids all three.

Option B — Brave Search API

1. Go to api.search.brave.com ↗ and sign up for a free API key (2 000 queries/month free).
2. In BroClaw → Settings → Search, select Brave and paste your key.

Brave Search API supports CORS natively — no proxy or Docker needed.

Option C — SerpAPI

1. Sign up at serpapi.com ↗ (100 free searches/month).
2. In BroClaw → Settings → Search, select SerpAPI and paste your key.

SerpAPI routes through BroClaw's service worker proxy to handle CORS — no setup needed.

🔌 MCP Servers

Connect any Model Context Protocol (MCP) server and BroClaw discovers its tools automatically — no code changes, no rebuild. Once connected, the agent can call those tools in chat exactly like its built-in ones (writing files, running code, etc.) — you just ask for what you want and the agent picks the right tool itself.

How it works

BroClaw talks to MCP servers over plain HTTP from inside your browser tab — the same way it already talks to Ollama. There's no built-in list of supported servers; you paste a URL into Settings → Connectors → MCP Servers and BroClaw asks that server what tools it has.

This only works for servers that speak MCP's Streamable HTTP transport. Most MCP servers you'll find described as npx -y some-package use a different transport called stdio (they only talk over a process's standard input/output) — a browser tab cannot start a process directly, so those need a small local bridge first (see Option B). Every connection — direct, bridged, or authenticated — ends up looking identical to BroClaw once it's added: just a URL, optionally with headers.

Once a server shows a green dot in Settings, its tools are simply available to the agent in every chat — there's no per-chat "enable this tool" step. If you connect a weather server and a GitHub server, just ask "what's the weather in Tokyo, and what are the open issues on my repo?" and the agent calls both automatically.

Option A — Direct connect (no bridge needed)

If a server is already reachable over HTTP and allows browser connections (sends CORS headers for this site), you can connect straight away — exactly like adding an Ollama endpoint:

1. Get the server's URL — e.g. https://mcp.example.com/mcp, or a local one already running on your machine such as http://localhost:8000/mcp.
2. In BroClaw → Settings → Connectors, scroll to MCP Servers.
3. Enter a name and paste the URL, then click + Add server.
4. BroClaw connects immediately and lists how many tools it found. A green dot means it's ready to use in chat.

If the add fails with a network error, the server most likely isn't CORS-enabled for browser clients. That's a server-side setting (most MCP frameworks call it allowed_origins or similar) — see Option B below if you can't change it.

Option B — Bridging a local stdio server with mcp-proxy

Most local MCP servers you'll see in setup guides — including code-sandbox servers like sandbox-mcp — are stdio-only. mcp-proxy ↗ is a small, widely-used open-source tool that spawns the stdio server for you and exposes it as a local HTTP endpoint BroClaw can reach — the same role Caddy plays for SearXNG above.

Browser (BroClaw)
    ↓ fetch POST/GET http://localhost:8811/mcp
mcp-proxy :8811  (HTTP \u2194 stdio bridge)
    ↓ spawns & talks stdio to
Your MCP server  (e.g. npx -y @pottekkat/sandbox-mcp)
    ↓ e.g. runs code inside
Docker container (isolated, ephemeral)

Step 1 — Install mcp-proxy

# Requires Python 3.10+ and uv (or pipx)
uvx mcp-proxy --help   # downloads & runs on first use, no install step needed

# or install it once:
pipx install mcp-proxy

Step 2 — Start the bridge, pointing it at your MCP server's stdio command

Example using sandbox-mcp (runs arbitrary code in isolated Docker containers — requires Docker Desktop running):

uvx mcp-proxy --port=8811 -- npx -y @pottekkat/sandbox-mcp

Swap the part after -- for any other stdio MCP server's normal launch command — the pattern is identical regardless of which one you use.

Step 3 — Add it in BroClaw

1. In BroClaw → Settings → Connectors → MCP Servers, enter a name (e.g. "Sandbox") and the URL http://localhost:8811/mcp.
2. Click + Add server. BroClaw connects through the bridge and lists the tools it found.
3. Leave the mcp-proxy terminal window running in the background while you use BroClaw — closing it disconnects the server (the same as quitting Ollama).

Option C — Servers that require auth (tokens, API keys)

Auth headers work the same way for every Streamable HTTP MCP connection — cloud-hosted, self-hosted on your own server, or local (including a local mcp-proxy bridge). There's nothing service-specific about it: whatever sits behind the URL, BroClaw attaches the same headers to every request it sends — the initial handshake, tool discovery, and every tool call. When adding a server, expand 🔐 Auth headers (optional) and enter one header per line as Name: Value, for example:

Authorization: Bearer sk-abc123
X-Api-Key: my-key

These are sent on every request to that server, the same way server.headers is already used for the session-id handshake. They're stored in localStorage alongside the server's URL — anyone with access to this browser profile can read them, so don't use this on a shared or public machine. To rotate or update a token later, click 🔐 Auth on that server's card in Settings, edit the textarea, and save — BroClaw reconnects automatically.

The one exception — stdio-only servers: a handful of MCP servers (most commonly database connectors, e.g. @modelcontextprotocol/server-postgres) are stdio-only and take their credential as a command-line argument or environment variable when launched, not as an HTTP header. For those, the credential is supplied at the mcp-proxy step in Option B instead of in BroClaw's Auth headers field — see Example 4 below.

Worked examples

A few concrete setups, covering the most common shapes of MCP server you'll run into.

Example 1 — Cloud server, no auth (direct connect)

Some hosted MCP servers are open to any browser, no key required — good for trying things out. If you have one's URL handy:

1. Name: Public Demo, URL: https://example-mcp.fly.dev/mcp (substitute the real URL).
2. Leave 🔐 Auth headers empty and click + Add server.
3. If it connects, you'll see its tool count immediately — no Option B or C needed.

Example 2 — Cloud SaaS server with a bearer token

Most production MCP servers (search APIs, project-management tools, CRMs) require a key. This is Option A + Option C together:

1. Get an API key from the service's dashboard.
2. Name: Linear (or whatever the service is), URL: the server's MCP endpoint, e.g. https://mcp.linear.app/mcp.
3. Expand 🔐 Auth headers and enter: Authorization: Bearer <your-api-key>
4. Click + Add server. A 401/403 here means the header name or token is wrong — check the service's MCP docs for the exact header it expects (some use X-Api-Key instead of Authorization).

Example 3 — Local stdio server, no credentials (Option B alone)

A filesystem or sandbox tool that just needs to run locally, with nothing to authenticate:

uvx mcp-proxy --port=8811 -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

Then add http://localhost:8811/mcp in BroClaw with no auth headers. The path after the package name (/Users/you/projects) restricts that server to one folder — check the server's own README for its exact arguments.

Example 4 — Local stdio server with a built-in credential (database, Option B + the stdio exception from Option C)

Database connectors are the classic case where the credential lives in the launch command, not in BroClaw's UI:

uvx mcp-proxy --port=8811 -- npx -y @modelcontextprotocol/server-postgres "postgresql://user:password@localhost:5432/mydb"

Add http://localhost:8811/mcp in BroClaw with no auth headers — the credential never leaves your machine's terminal. The same pattern applies to any stdio server that takes a connection string, API key, or token as a CLI argument or environment variable (e.g. GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx npx -y @modelcontextprotocol/server-github, bridged the same way).

Example 5 — Self-hosted server on your LAN, custom header

Not every server is "cloud" or "localhost" — e.g. a Streamable HTTP MCP server you run on a home server or office machine:

1. Name: Home Assistant, URL: http://192.168.1.50:9000/mcp (your machine's LAN IP).
2. If that server checks a shared secret, expand 🔐 Auth headers and add whatever header it expects, e.g. X-Internal-Token: my-shared-secret.
3. Click + Add server. This works exactly like Example 2 — auth headers don't care whether the IP is a public domain or a private LAN address.

Managing connected servers

Each server in Settings shows a green/red status dot, how many tools it exposes, and four controls: a checkbox to temporarily disable it without removing it, Reconnect to refresh its tool list after restarting the server, 🔐 Auth to view or update its auth headers, and Remove to delete it entirely. Disabled servers are not offered to the agent at all, so you can keep several configured and only turn on the one you need for a given task.

A note on stdio support

BroClaw is a browser-only app with no backend process, so it can never spawn a child process or speak stdio directly — this is a hard limitation of running inside a browser tab, not something specific to BroClaw. Every MCP client that supports stdio servers natively (Claude Desktop, Claude Code, Cursor, etc.) does so because it ships with its own Node.js/Electron backend able to call child_process.spawn(). BroClaw deliberately stays browser-only, so stdio servers always go through the mcp-proxy bridge described in Option B above — there is no plan to add a backend just to remove that step.

Troubleshooting

⚡ Skills

Skills are one-click prompt templates that accelerate common tasks.

Using Skills

1. Click the Skills tab in the left sidebar.
2. Browse or search by keyword (e.g. "research", "debug", "email").
3. Click Use ↗ — the skill prompt appears in the chat input.
4. Replace {input} or {topic} with your specific content.
5. Press Enter or click Send — the agent takes it from there.

Built-in Skills

Creating Custom Skills

Go to the Skills tab and click + New Skill. Give it a name, description, and a prompt template. Use {input} as the placeholder for what the user types.

# Example custom skill prompt:
You are a senior product manager. Given the following feature request:
{input}

Write a one-page PRD covering: problem statement, user story, success metrics, and out-of-scope items.

Agent Actions Reference

Writing Good System Prompts

• Be specific about output format: "Return results as a markdown table with columns: Name, URL, Summary"
• Mention constraints: "Only use information from .gov or .edu sources"
• Set scope: "Create all files in a sub-folder named output/"
• Avoid vague verbs like "help" — use action verbs: "research", "build", "summarise", "compare"