docs: rebuild KB in OKF v0.1 with live-verified facts

Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
2026-08-28 07:57:13 -07:00
1 parent 552d1ef8bf
commit 02883d3ed2
@@ -0,0 +1,194 @@
+---
+type: concept
+title: SearXNG Tuning
+description: Configuration decisions for a fast, private, useful self-hosted SearXNG instance.
+tags:
+  - searxng
+  - search
+  - privacy
+  - configuration
+  - unverified
+verified: 2026-08-28
+timestamp: 2026-08-11
+resource: https://docs.searxng.org
+---
+
+# SearXNG Tuning
+
+SearXNG is a metasearch engine. It aggregates 274 or more upstream search services into one result set. Configuration lives in `settings.yml`. The recommended deployment is Docker Compose with a Valkey container.
+
+This page lists the settings that matter for speed, privacy, and useful results.
+
+> **Your setup:** Pi Web Access calls a remote SearXNG at [`192.168.0.143:8081`](../pi/packages/pi-web-access.md) (dankclaw). Apply these settings to that host, not to this machine.
+
+## Plan the Deployment
+
+```mermaid
+graph LR
+    A[Browser or Agent] --> B[SearXNG container]
+    B --> C[Valkey cache + limiter]
+    B --> D[Engine request pool]
+    D --> E[Google News]
+    D --> F[DuckDuckGo]
+    D --> G[Wikipedia]
+```
+
+Deploy with the official Docker Compose file. It ships a `searxng-valkey` container (`valkey/valkey:9-alpine`). Valkey replaced Redis as the default cache. Mount your config at `./core-config/:/etc/searxng`.
+
+```yaml
+services:
+  searxng:
+    image: docker.io/searxng/searxng:latest
+    ports:
+      - "8081:8080"
+    volumes:
+      - ./core-config/:/etc/searxng/:Z
+    depends_on:
+      - searxng-valkey
+
+  searxng-valkey:
+    image: docker.io/valkey/valkey:9-alpine
+    restart: always
+```
+
+## Core Settings
+
+```yaml
+use_default_settings: true
+server:
+  secret_key: "change-this"   # or $SEARXNG_SECRET
+  base_url: "http://192.168.0.143:8081/"   # or $SEARXNG_BASE_URL
+  limiter: true
+  method: "POST"
+
+search:
+  default_lang: "en"
+  default_locale: "en-US"
+  safe_search: 0
+  formats:
+    - html
+    - json
+```
+
+Change `secret_key`. Set `base_url` to the public address. Use `POST` for privacy. Enable the `json` format for the agent.
+
+## Rate Limiting
+
+Enable the limiter and point it at Valkey. Without a limiter, an upstream engine can block SearXNG's IP.
+
+```yaml
+server:
+  limiter: true
+
+valkey:
+  url: valkey://searxng-valkey:6379/0
+```
+
+The limiter uses a sliding window per IP:
+
+| Window | HTML limit | JSON/API limit |
+|--------|-----------|----------------|
+| 20 seconds | 15 | 4 per 3600 s |
+| 600 seconds | 150 | 4 per 3600 s |
+
+Suspicious IPs get a much lower budget (2 in 20 s, 10 in 600 s). The agent that hits the JSON endpoint repeatedly can trip the 4-per-hour API limit. Back off or make the agent part of a trusted group.
+
+## Outgoing Pool
+
+```yaml
+outgoing:
+  request_timeout: 3.0
+  max_request_timeout: 10.0
+  pool_connections: 100
+  pool_maxsize: 20
+  enable_http2: true
+  keepalive_expiry: 5.0
+  retries: 3
+```
+
+A short `request_timeout` keeps results snappy. `enable_http2` multiplexes connections. More `retries` makes results more reliable but slower.
+
+## Engine Selection
+
+Default engine state (current SearXNG):
+
+| Engine | Default state | Note |
+|--------|---------------|------|
+| DuckDuckGo | Enabled | Reliable general search |
+| Wikipedia | Enabled | Encyclopedia lookups |
+| Google News | Enabled | News results |
+| Google (main) | Inactive | Cloudflare CAPTCHA often blocks it |
+| Bing | Disabled | Blocked upstream |
+
+Keep only the engines you need. Fewer engines means faster responses.
+
+```yaml
+use_default_settings:
+  engines:
+    keep_only:
+      - duckduckgo
+      - wikipedia
+      - google news
+```
+
+Make an engine private to one agent with a token:
+
+```yaml
+engines:
+  - name: arch wiki
+    engine: archlinux
+    tokens: ['my-secret-token']
+```
+
+## Useful Plugins
+
+```yaml
+plugins:
+  searx.plugins.unit_converter.SXNGPlugin:
+    active: true
+  searx.plugins.calculator.SXNGPlugin:
+    active: true
+  searx.plugins.self_info.SXNGPlugin:
+    active: true
+```
+
+The hostnames plugin filters or rewrites results. It needs a separate `hostnames:` block:
+
+```yaml
+hostnames:
+  remove:
+    - '(.*\.)?facebook.com$'
+  high_priority:
+    - '(.*\.)?wikipedia.org$'
+```
+
+## JSON API for the Agent
+
+The agent uses the JSON format. Confirm that it returns structured data:
+
+```bash
+curl 'http://192.168.0.143:8081/search?q=test&format=json'
+```
+
+The response contains `results`, `query`, `number_of_results`, and `suggestions`. The `/config` endpoint lists engine availability.
+
+## Verify the Instance
+
+1. Open the HTML interface and run a test query.
+2. Confirm that the `json` format returns data.
+3. Confirm that the limiter page appears on rapid repeats.
+
+## Citations
+
+- SearXNG documentation: <https://docs.searxng.org>
+- SearXNG outgoing settings: <https://docs.searxng.org/admin/settings/settings_outgoing.html>
+- SearXNG engine settings: <https://docs.searxng.org/admin/settings/settings_engines.html>
+- SearXNG Valkey settings: <https://docs.searxng.org/admin/settings/settings_valkey.html>
+- SearXNG limiter: <https://docs.searxng.org/admin/searx.limiter.html>
+- SearXNG plugins: <https://docs.searxng.org/admin/settings/settings_plugins.html>
+- Docker Compose install: <https://docs.searxng.org/admin/installation-docker.html>
+
+## See Also
+
+- [VPN Routing for SearXNG](vpn-routing.md) — Route the outbound path through a VPN.
+- [Agentic Search Best Practices](agentic-search-best-practices.md) — Use the JSON format well.