SearXNG is a private, meta-searching engine that aggregates results from over 70 search engines. Unlike traditional search engines, it does not pass data to third parties and performs no tracking.
Create a dedicated namespace for SearXNG:
export KUBECONFIG=/path/to/kubeconfig
kubectl create namespace searxng --dry-run=client -o yaml | kubectl apply -f -
Add the SearXNG Helm chart repository:
helm repo add kubitodev https://charts.kubito.dev
helm repo update kubitodev
Create a values file (searxng-values.yaml) with the following configuration:
# SearXNG Values File
# Source: https://artifacthub.io/packages/helm/kubitodev/searxng
config:
settings:
enabled: true
data: |
use_default_settings: true
server:
secret_key: "<GENERATE-A-RANDOM-KEY-WITH-openssl-rand-hex-32>"
limiter: false
image_proxy: true
port: 8080
bind_address: "0.0.0.0"
ui:
static_use_hash: true
search:
safe_search: 0
autocomplete: ""
default_lang: ""
formats:
- html
- json # Critical for agentic tools!
limiter:
enabled: true
data: |
[botdetection.ip_limit]
link_token = true
granian:
enabled: true
workers: 1
blocking_threads: 4
backpressure: 20
http1_buffer_size: 8192
http1_keep_alive: false
log_level: warning
log_access_enabled: false
service:
type: ClusterIP
port: 8080
ingress:
enabled: true
className: ""
annotations: {}
hosts:
- host: search.domain.tld # Replace with your FQDN
paths:
- path: /
pathType: Prefix
tls: []
startupProbe: {}
livenessProbe:
httpGet:
path: /
port: http
readinessProbe:
httpGet:
path: /
port: http
resources: {}
nodeSelector: {}
tolerations: []
affinity: {}
⚠️ Important Notes:
- Replace
<GENERATE-A-RANDOM-KEY-WITH-openssl-rand-hex-32>with a secure random key- Replace
search.domain.tldwith your actual FQDN- The JSON format entry in
search.formatsis essential for Agentic Tools
Install SearXNG using the prepared values file:
export KUBECONFIG=/path/to/kubeconfig
helm upgrade --install searxng kubitodev/searxng \
-n searxng \
-f /path/to/searxng-values.yaml \
--version 1.1.4 \
--wait \
--timeout 300s
The ingress is created automatically when ingress.enabled: true is set in the values file. Verify after deployment:
kubectl get ingress -n searxng
Expected output:
NAME CLASS HOSTS ADDRESS PORTS AGE
searxng-searxng traefik search.domain.tld <EXTERNAL-IP> 80 1m
Check pod status:
kubectl get all -n searxng
SearXNG provides a JSON endpoint designed specifically for programmatic access by AI agents and automated workflows.
curl "https://search.domain.tld/search?q=example+query&format=json&limit=5"
The JSON response contains the following fields:
| Field | Type | Description |
|---|---|---|
query |
string | The searched query |
results |
array[] | Array of search results |
answers |
array[] | Direct answers (if available) |
corrections |
array[] | Spelling corrections |
infoboxes |
array[] | Infobox data (e.g., from Wikipedia) |
suggestions |
array[] | Suggestions for related searches |
Each result in results contains:
| Field | Type | Description |
|---|---|---|
title |
string | Result title |
url |
string | Target URL |
content |
string | Snippet/content description |
engine |
string | Search source (e.g., google, bing, wikipedia) |
category |
string | Category (general, news, science, etc.) |
publishedDate |
string | Publication date (if available) |
author |
string | Author (if available) |
img_src |
string | Thumbnail URL |
parsed_urls |
array[] | Parsed URL components |
engines |
array[] | Search engines that returned this result |
positions |
array[] | Positions in individual search engines |
score |
number | Relevance score |
# Search for technical documentation
curl -s "https://search.domain.tld/search?q=kubernetes+deployment+guide&format=json&categories=general&limit=3" \
| jq -r '.results[] | "\(.title)\n\(.url)\n\(.content[:200])\n"'
| Parameter | Value | Description |
|---|---|---|
format |
json |
Always use JSON for machine-readable output |
limit |
3-10 |
Number of results per search |
safesearch |
0 |
No safe-search for full results |
engines |
google,bing |
Specify search engines |
categories |
general,news |
Category filter |
time_range |
week,month |
Time range filter |
Install the official SearXNG search skill from Hermes Agent:
hermes skills install official/research/searxng-search
This creates the skill under ~/.hermes/skills/research/searxng-search/.
Add the SearXNG URL to the .env file:
# File: ~/.hermes/.env
SEARXNG_URL=https://search.domain.tld
Replace
search.domain.tldwith your actual SearXNG installation FQDN.
Restart the Hermes gateway to load the new environment variable:
hermes gateway restart
Check that the skill is recognized and the SearXNG instance is reachable:
# Test SearXNG connection
curl -s --max-time 5 "${SEARXNG_URL}/search?q=test&format=json" | head -c 200
Expected output (excerpt):
{"query": "test", "results": [...], "answers": [], "corrections": [], "infoboxes": [], "suggestions": [...]}
Cause: SEARXNG_URL is not set or unreachable.
Solution:
# Check environment variable
echo $SEARXNG_URL
# Test connectivity
curl -s --max-time 5 "${SEARXNG_URL}/search?q=test&format=json" | head -c 200
Cause: Old SearXNG version or incorrect configuration.
Solution:
formats: [json] is included in config.settings.dataCause: SearXNG instance is not running or incorrect URL.
Solution:
# Check pod status
kubectl get pods -n searxng
kubectl logs -n searxng deployment/searxng
Cause: SearXNG instance blocks requests or rate limiting.
Solution:
Cause: Public SearXNG instances are often overloaded.
Solution:
time_range parameter for temporal filteringengines parameter for specific search engineslimiter appropriately for your infrastructureformat=json for programmatic access--max-time on curl commands (recommended: 10 seconds)+)