searxng

name

searxng

description

This skill should be used when the agent needs to perform web searches, look up current information online, or gather search results from the internet. Provides privacy-respecting web search through a self-hosted SearXNG instance with structured JSON output. Responds to "search the web for", "look this up online", "find recent articles about", "what does Google say about", "web search", or any task requiring live internet search results. No API keys or external accounts needed.

SearXNG — Privacy-Respecting Web Search

SearXNG is a self-hosted metasearch engine that aggregates results from 70+ search engines (Google, Bing, DuckDuckGo, etc.) without tracking or profiling. It provides a JSON API that works well for agent research loops.

Usage Posture

When using SearXNG for research:

• Start with a focused query. Narrow beats broad. "rust async runtime comparison 2026" beats "rust async".
• Fetch 5–10 results per query. More than 10 rarely adds signal. Use jq '.results[:5]' or [:10].
• Use categories to cut noise. categories=it for tech, categories=news for recency, categories=science for academic sources.
• Use time_range for freshness. time_range=week or time_range=month when recency matters. Omit it for evergreen topics.
• Paginate only when the first page is promising but incomplete. Add pageno=2 if you see relevant results but need more.
• Handle zero or poor results by reformulating. Try synonyms, drop qualifiers, or switch categories before concluding nothing exists.
• Combine multiple targeted searches over one broad search. Two precise queries ("SearXNG docker setup" + "SearXNG JSON API") beat one vague query ("SearXNG").

Installation

Docker (recommended)

docker run -d \
  --name searxng \
  --restart always \
  -p 8888:8080 \
  searxng/searxng:latest

This runs SearXNG on http://localhost:8888. The --restart always flag ensures it starts on boot.

Docker Compose (alternative)

# docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8888:8080"
    restart: always

docker compose up -d

Enable JSON Output

By default, SearXNG may not have JSON format enabled. To enable it:

# Find the settings file inside the container
docker exec searxng cat /etc/searxng/settings.yml | grep -A5 formats

# If json is not listed, override settings:
docker cp searxng:/etc/searxng/settings.yml ./settings.yml
# Edit settings.yml: under 'search:', add 'formats: [html, json, csv, rss]'
docker cp ./settings.yml searxng:/etc/searxng/settings.yml
docker restart searxng

Verify

curl -s "http://localhost:8888/search?q=test&format=json" | head -c 200

You should see JSON output with search results.

Quick Search

# Basic search — top 5 results as JSON
curl -s "http://localhost:8888/search?q=YOUR+QUERY&format=json" | jq '.results[:5]'

# Titles and URLs only
curl -s "http://localhost:8888/search?q=YOUR+QUERY&format=json" \
  | jq -r '.results[:5] | .[] | "\(.title)\n\(.url)\n---"'

# With content snippets (best for AI agents)
curl -s "http://localhost:8888/search?q=YOUR+QUERY&format=json" \
  | jq -r '.results[:5] | .[] | "## \(.title)\n\(.url)\n\(.content)\n"'

URL Encoding

Encode spaces as + or %20 in query strings:

# These are equivalent
curl -s "http://localhost:8888/search?q=rust+async+tutorial&format=json"
curl -s "http://localhost:8888/search?q=rust%20async%20tutorial&format=json"

Search Categories

Target specific content types with &categories=:

Category	Use For
general	Default web search
images	Image search
videos	Video search
news	Recent news
music	Music/audio
files	File downloads
it	Tech/programming
science	Academic/scientific
social+media	Social platforms

# Search only tech/programming sources
curl -s "http://localhost:8888/search?q=rust+async&format=json&categories=it" | jq '.results[:5]'

# Recent news only
curl -s "http://localhost:8888/search?q=openai&format=json&categories=news" | jq '.results[:5]'

Advanced Parameters

Parameter	Values	Description
format	json, csv, rss, html	Output format
language	en, de, fr, etc.	Result language
time_range	day, week, month, year	Recency filter
safesearch	0, 1, 2	Safe search level
pageno	1, 2, ...	Page number

# German results from the past week
curl -s "http://localhost:8888/search?q=ki+nachrichten&format=json&language=de&time_range=week"

# Page 2 of results
curl -s "http://localhost:8888/search?q=python+tutorial&format=json&pageno=2"

Troubleshooting

# Check if running
docker ps | grep searxng

# View logs
docker logs --tail 50 searxng

# Restart
docker restart searxng

# Full restart (remove + recreate)
docker rm -f searxng
docker run -d --name searxng --restart always -p 8888:8080 searxng/searxng:latest

Common Issues

• "Connection refused" — Container isn't running. Check docker ps and start it.
• "format not available" — JSON output isn't enabled in settings. See installation section.
• Slow results — SearXNG queries multiple engines. First query after restart is slower.

Configuration

SearXNG is highly configurable via /etc/searxng/settings.yml inside the container. Key settings:

• Engines — Enable/disable specific search engines
• Formats — Which output formats are available
• UI — Language, theme, default settings
• Rate limiting — Protect against abuse

See SearXNG documentation for full reference.

Links

• Docs: https://docs.searxng.org/
• GitHub: https://github.com/searxng/searxng
• Public Instances: https://searx.space/ (if you don't want to self-host)