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
parent 552d1ef8bf
commit 02883d3ed2
116 changed files with 13008 additions and 0 deletions
@@ -0,0 +1,189 @@
+---
+type: concept
+title: VPN Routing for SearXNG
+description: Send only SearXNG outbound requests through a VPN while leaving all other local traffic alone.
+tags:
+  - vpn
+  - searxng
+  - networking
+  - proxy
+  - unverified
+verified: 2026-08-28
+timestamp: 2026-08-19
+resource: https://docs.searxng.org/admin/settings/settings_outgoing.html
+---
+
+# VPN Routing for SearXNG
+
+SearXNG talks to many upstream engines. Some of them rate-limit or block the source IP. You can send only that outbound path through a VPN and leave every other process on the host untouched.
+
+This page gives four working patterns. Choose the one that matches how you run SearXNG.
+
+> **Your setup:** SearXNG runs on another host at `192.168.0.143:8081` (dankclaw). Apply the Docker patterns on that host. The proxy pattern works from any host.
+
+## The Goal
+
+```mermaid
+graph LR
+    A[Local agent] --> B[SearXNG]
+    B -->|through VPN| C[Upstream engines]
+    D[Other local traffic] --> E[Plain internet]
+```
+
+The VPN carries only the SearXNG outbound path. Nothing else changes.
+
+## Pattern 1: SearXNG Proxy Setting
+
+SearXNG supports HTTP and SOCKS proxies natively. Point the outbound settings at a local proxy that exits through the VPN.
+
+```yaml
+outgoing:
+  proxies:
+    all://:
+      - socks5://vpn-proxy:1080
+  extra_proxy_timeout: 10.0
+```
+
+Apply the proxy to one engine only:
+
+```yaml
+engines:
+  - name: google
+    engine: google
+    proxies:
+      https:
+        - socks5://vpn-proxy:1080
+```
+
+To force the VPN source IP on a multi-homed host, add `source_ips` and pin the engine to IPv4:
+
+```yaml
+outgoing:
+  source_ips:
+    - 10.8.0.2
+
+engines:
+  - name: my-search
+    engine: duckduckgo
+    network: ipv4
+```
+
+## Pattern 2: Gluetun (Recommended)
+
+Gluetun is a VPN container (WireGuard or OpenVPN). Attach SearXNG to its network namespace. Only SearXNG shares the tunnel. Other containers stay on the default network.
+
+```yaml
+services:
+  gluetun:
+    image: qmcgaw/gluetun:latest
+    cap_add: [NET_ADMIN]
+    devices: [/dev/net/tun:/dev/net/tun]
+    ports:
+      - "8081:8080"
+    environment:
+      VPN_SERVICE_PROVIDER: mullvad
+      VPN_TYPE: wireguard
+      WIREGUARD_PRIVATE_KEY: <key>
+    restart: always
+
+  searxng:
+    image: searxng/searxng:latest
+    network_mode: service:gluetun
+    depends_on:
+      - gluetun
+    volumes:
+      - ./core-config:/etc/searxng
+    restart: unless-stopped
+```
+
+Put the port mapping on the `gluetun` service. The `searxng` container does not get its own ports.
+
+## Pattern 3: Dedicated Internal Network
+
+Create a network that only SearXNG shares with a lighter VPN client.
+
+```yaml
+services:
+  searxng:
+    image: searxng/searxng:latest
+    networks:
+      - searxng-vpn
+    volumes:
+      - ./core-config:/etc/searxng
+
+  vpn-client:
+    image: dperson/openvpn-client:latest
+    networks:
+      - searxng-vpn
+    cap_add:
+      - NET_ADMIN
+
+networks:
+  searxng-vpn:
+    internal: true
+```
+
+An OpenVPN client container is simpler than Gluetun when your provider uses OpenVPN.
+
+## Pattern 4: Run SearXNG Inside the VPN Container
+
+```yaml
+services:
+  searxng:
+    image: searxng/searxng:latest
+    network_mode: "container:vpn-client"
+    depends_on:
+      - vpn-client
+    volumes:
+      - ./core-config:/etc/searxng
+
+  vpn-client:
+    image: dperson/openvpn-client:latest
+    cap_add: [NET_ADMIN]
+    environment:
+      VPN: server.address;username;password
+    restart: always
+```
+
+This pattern places the whole SearXNG process inside the tunnel namespace. The host sees the tunnel as the only route for SearXNG.
+
+## Compare the Patterns
+
+| Pattern | Complexity | Isolation | Per-engine control |
+|---------|-----------|-----------|--------------------|
+| Proxy setting | Low | Medium | Yes |
+| Gluetun | Medium | High | No |
+| Dedicated network | Medium | High | No |
+| Inside VPN container | Medium | Highest | No |
+
+## Decisions That Matter
+
+- A SOCKS proxy keeps the per-engine control. Use Pattern 1.
+- Gluetun gives the cleanest full-tunnel setup. Use Pattern 2.
+- Mullvad ships its own WireGuard keys for Gluetun.
+- An OpenVPN-only provider works with Pattern 3 or 4.
+
+## Verify the Route
+
+1. Run the instance with the VPN active.
+2. Query an IP-echo page through SearXNG.
+3. Confirm that the returned IP differs from your host IP.
+4. Confirm that unrelated host traffic keeps the host IP.
+
+```bash
+# From inside the tunnel with Gluetun
+docker exec gluetun curl -s ifconfig.me
+```
+
+## Citations
+
+- SearXNG outgoing settings: <https://docs.searxng.org/admin/settings/settings_outgoing.html>
+- SearXNG engine settings: <https://docs.searxng.org/admin/settings/settings_engines.html>
+- Gluetun: <https://github.com/qdm12/gluetun>
+- Connect a container to Gluetun: <https://github.com/qdm12/gluetun-wiki/blob/main/setup/connect-a-container-to-gluetun.md>
+- Docker Compose networking: <https://docs.docker.com/compose/networking/>
+
+## See Also
+
+- [SearXNG Tuning](searxng-tuning.md) — The instance these patterns protect.
+- [Agentic Search Best Practices](agentic-search-best-practices.md) — Proxy rotation and retries.