SearXNG Private Web Search for you and your agents

SearXNG is a self-hosted metasearch engine that lets you run private web search on your own machine. For local AI workflows, it pairs especially well with coding agents and local model hosts because it exposes a simple JSON search API.

Index#

Overview
Setup
Beginner usage
Pro usage
Cost savings guide
Privacy guide
Security guide
Appendix

Overview#

What it is. SearXNG is a metasearch engine that aggregates results from other search engines without storing user information or building profiles. It is a strong fit for privacy-conscious AI workflows because you can run it yourself and expose JSON search results to local tools. (SearXNG, SearXNG)

How this fits the stack

SearXNG handles private web search.
Ollama hosts local models on your machine.
Goose and OpenCode are the agent shells that call both of them.

That means there is no special "SearXNG-to-Ollama" integration by itself. The common pattern is: agent uses Ollama for inference and SearXNG for web search. (SearXNG, Goose Custom Extensions, OpenCode MCP)

Why this setup works

Local-first web search: run your own search layer instead of sending prompts to hosted search APIs. (SearXNG)
Agent-friendly API: the built-in Search API supports JSON output when enabled, which makes it easy to wire into MCP servers and local tools. (SearXNG)
Clean separation of concerns: Ollama handles models, while SearXNG handles retrieval. This keeps the stack simple to reason about.

Setup#

1) Create config directory and settings.yml#

Create the config directory and a minimal settings.yml before starting the container. This keeps defaults, enables JSON output for MCP integrations, and binds to all container interfaces so Docker port-forwarding works. The settings docs show use_default_settings plus server secret_key, and the search settings list default formats (HTML only by default). (SearXNG, SearXNG, SearXNG)

mkdir -p ./searxng/config/ ./searxng/data/
cat > ./searxng/config/settings.yml << 'EOF'
use_default_settings: true

search:
  # Enable JSON output for /search?format=json
  formats:
    - html
    - json

server:
  # Bind to all interfaces so Docker port-forwarding works
  # (host-side restriction is handled by -p 127.0.0.1:8080:8080)
  bind_address: "0.0.0.0"
  # Change this before exposing beyond localhost
  secret_key: "change-me-please"
EOF

2) Run a local container#

The official container guide documents Docker-based setup; here is a minimal local example that binds to localhost:8080 and persists config/cache to local volumes. (SearXNG)

cd ./searxng/

docker run --name searxng -d \
  -p 127.0.0.1:8080:8080 \
  -v "./config/:/etc/searxng/" \
  -v "./data/:/var/cache/searxng/" \
  docker.io/searxng/searxng:latest

3) Verify the search API#

The Search API supports format=json when json is present in search.formats. (SearXNG, SearXNG)

curl "http://localhost:8080/search?q=searxng&format=json"

4) Optional: start Ollama locally#

If you want a full local stack, start Ollama so Goose or OpenCode can use local models while SearXNG handles search.

ollama serve
ollama pull qwen3.5:3b

Quick checks:

curl http://localhost:11434/api/version
ollama ls

5) Connect Goose to SearXNG#

Goose supports custom MCP extensions, which makes SearXNG straightforward to add as a local search tool. (Goose Custom Extensions)

Start the MCP server:

npx mcp-searxng

Add a Custom Extension in Goose with:

# Extension command
npx mcp-searxng

# Extension env
SEARXNG_URL=http://localhost:8080

If you also want Goose to use Ollama for inference:

Desktop: configure the Ollama provider and set API Host to http://localhost:11434.
CLI:

export GOOSE_PROVIDER=ollama
export OLLAMA_HOST=http://localhost:11434
export GOOSE_MODEL=qwen3.5:3b
goose session --name private-search

6) Connect OpenCode to SearXNG#

OpenCode supports MCP servers for tools and OpenAI-compatible providers for local inference. That makes SearXNG + Ollama + OpenCode a clean single-machine workflow. (OpenCode MCP, OpenCode Config, OpenCode Providers)

Add the SearXNG MCP server and optional Ollama provider to ~/.config/opencode/opencode.json or a project-local ./opencode.json:

{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3.5:3b": {
"name": "Qwen 3.5 3B (local)"
}
}
}
},
"model": "ollama/qwen3.5:3b",
"small_model": "ollama/qwen3.5:3b",
"mcp": {
"searxng": {
"type": "local",
"command": ["uvx", "mcp-searxng"],
"enabled": true,
"environment": {
"SEARXNG_URL": "http://localhost:8080"
}
}
},
"tools": {
"websearch": false
}
}

This tells OpenCode to use Ollama for model calls, SearXNG for web search, and the built-in hosted websearch tool stays off.

Beginner usage#

Use SearXNG directly: open http://localhost:8080 and search in the browser.
Use JSON for tooling: call /search?format=json and pass q, categories, or engines. (SearXNG)
Goose flow: start a Goose session and ask it to search the web; if it asks which tool to use, pick your SearXNG extension.
OpenCode flow: launch opencode, select your Ollama-backed model with /models, and ask for a search-based summary or research task.
Simple mental model: SearXNG retrieves, Ollama reasons, Goose/OpenCode orchestrate.

Pro usage#

Trim engines to reduce noise and outbound requests using engines.remove or engines.keep_only. The settings docs show how to override and filter engines with use_default_settings. (SearXNG)
Pin SearXNG as the only search path in OpenCode by disabling the built-in websearch tool. (OpenCode Tools)
Use local models with Goose so both inference and search stay on your machine as much as possible. (Goose Providers)
Use smaller Ollama models for search-heavy tasks and keep larger hosted models only for difficult refactors.
Keep the instance local by binding Docker to 127.0.0.1, or place it behind a VPN/reverse proxy only if you truly need remote access. (SearXNG)
Use proxies or Tor if you want extra anonymity when SearXNG queries upstream search engines. (SearXNG)

Cost savings guide#

No per-query API fees when you self-host SearXNG; you only pay local compute and bandwidth.
Avoid hosted search add-ons by routing agent search through your own SearXNG instance.
Pair SearXNG with Ollama to cut both search spend and inference spend for everyday work.
Limit engines to reduce rate limits, latency, and background resource usage.

Privacy guide#

Run your own instance: private instances keep source code, logging settings, and private data under your control. (SearXNG)
SearXNG minimizes tracking by not sending cookies to external search engines and by generating a random browser profile per request. (SearXNG)
Local Ollama keeps prompts on-device when it is bound to localhost.
Disable OpenCode sharing if you want stricter local-only operation. (OpenCode Share)
Use Goose allowlists and .gooseignore when working in sensitive repos. (Goose Allowlists, Goose Ignore)

Security guide#

Bind SearXNG to localhost for single-user setups using Docker's host-side restriction (-p 127.0.0.1:8080:8080). (SearXNG)
Set a strong secret_key before exposing the instance beyond your machine. (SearXNG, SearXNG)
Use use_default_settings: true and override only what you need to reduce misconfiguration risk. (SearXNG)
Keep Ollama on 127.0.0.1 unless you add firewall rules and authentication in front of it.
Scope tool access in Goose and OpenCode so search and shell tools are not broader than they need to be. (Goose Allowlists, OpenCode Tools)

Appendix#

Minimal settings.yml

use_default_settings: true

search:
  formats:
    - html
    - json

server:
  bind_address: "0.0.0.0"
  secret_key: "change-me-please"

Quick checklist

SearXNG running locally at http://localhost:8080
SearXNG settings.yml has json in search.formats
Ollama running locally at http://localhost:11434 if you want local inference
Goose extension added with SEARXNG_URL=http://localhost:8080
OpenCode config includes the SearXNG MCP server

Two common local stacks

# Goose + Ollama + SearXNG
ollama serve
npx mcp-searxng
goose session --name private-search

# OpenCode + Ollama + SearXNG
ollama serve
opencode