home / skills / openclaw / skills / private-web-search-searchxng

private-web-search-searchxng skill

safe

/skills/adelpro/private-web-search-searchxng

This skill enables private self-hosted web search using SearXNG, protecting privacy, blocking external APIs, and avoiding tracking in AI workflows.

npx playbooks add skill openclaw/skills --skill private-web-search-searchxng

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.9 KB

---
name: private-web-search-searchxng
description: Self-hosted private web search using SearXNG. Use when privacy is important, external APIs are blocked, you need search without tracking, or want to avoid paid search APIs.
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["docker", "curl", "jq"] },
        "install":
          [
            {
              "id": "docker",
              "kind": "bin",
              "command": "docker --version",
              "label": "Docker required",
            },
          ],
      },
  }
---

# Private Web Search (SearXNG)

Privacy-respecting, self-hosted metasearch engine for AI agents.

## Quick Setup

```bash
# 1. Start container
docker run -d --name searxng -p 8080:8080 -e BASE_URL=http://localhost:8080/ searxng/searxng

# 2. Enable JSON API
docker exec searxng sed -i 's/  formats:/  formats:\n    - json/' /etc/searxng/settings.yml
docker restart searxng

# 3. Verify
curl -sL "http://localhost:8080/search?q=test&format=json" | jq '.results[0]'
```

## Usage

### Basic Search

```bash
curl -sL "http://localhost:8080/search?q=YOUR_QUERY&format=json" | jq '.results[:10]'
```

### Using the Helper Script

```bash
./scripts/search.sh "openclaw ai" 5
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| SEARXNG_PORT | 8080 | Container port |
| SEARXNG_HOST | localhost | Server host |
| BASE_URL | http://localhost:8080 | Public URL |

## Available Engines

Google, Bing, DuckDuckGo, Brave, Startpage, Wikipedia, and more.

## Management

```bash
docker start searxng   # Start
docker stop searxng    # Stop
docker logs searxng    # View logs
docker rm searxng -f   # Remove
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| No results | Check `docker logs searxng` |
| 403 Forbidden | Enable JSON format (step 2) |
| Connection refused | Run `docker start searxng` |

Overview

This skill provides a self-hosted, privacy-respecting web search powered by SearXNG. It delivers metasearch results without tracking or reliance on paid external APIs, ideal for AI agents running in restricted or privacy-sensitive environments. The setup uses a lightweight containerized deployment and a simple JSON API for integrations.

How this skill works

The skill runs SearXNG in a Docker container and exposes a JSON search endpoint that aggregates results from multiple engines (Google, Bing, DuckDuckGo, Brave, Startpage, Wikipedia, etc.). It configures the JSON output format and offers helper scripts for querying and limiting results. Agents call the local /search?q=...&format=json endpoint to retrieve structured results for processing.

When to use it

You need private search without third-party tracking or telemetry.
External search APIs are blocked, rate-limited, or cost-prohibitive.
You want a local metasearch endpoint for AI agents in a secure network.
You require multi-engine aggregate results for broader coverage.
You prefer full control over search configuration and logging.

Best practices

Run SearXNG in Docker with a persistent configuration volume for custom settings.
Enable and verify the JSON API format to ensure structured responses for agents.
Limit exposed ports and bind to localhost or a private network to reduce attack surface.
Cache frequent queries at the agent level to reduce load and improve latency.
Monitor container logs and restart the container automatically via a supervisor or systemd.

Example use cases

An on-premise AI assistant that must avoid sending queries to external commercial search APIs.
A research pipeline that aggregates results from multiple engines for cross-checking claims.
A privacy-first chatbot deployed in a corporate network with no internet-facing services.
A development environment where external API keys cannot be used or shared.
A backup search service for applications when primary API providers are unavailable.

FAQ

How do I enable JSON output?

Edit the SearXNG settings to include the json format under formats, then restart the container. Example: modify /etc/searxng/settings.yml to add '- json' under formats.

What if I get no results or a 403 error?

Check the container logs with docker logs searxng; ensure JSON format is enabled and the container can reach search engines. A 403 often indicates the JSON format is not configured.