Self-Hosting

SearXNG Integration

SearXNG is the federated search backbone powering HyperSearchX. It aggregates results from Google, Bing, DuckDuckGo, Brave, Wikipedia, StackOverflow, GitHub, arXiv, Reddit, and HackerNews — simultaneously, without API keys.

One-command setup: Run hsx setup --searxng to automatically pull the Docker image, generate a config, and start SearXNG on port 4040.

Automated setup

bash

# Requires Docker to be installed and running
hsx setup --searxng

# Output:
# ── SearXNG (federated search backbone) ─────────────
#   Config: ~/.hypersearchx/searxng/settings.yml (created)
#   Port  : 4040 (container port 8080 → host 4040)
#   Image: pulling docker.io/searxng/searxng:latest
#   Container: creating on port 4040...
#   Health: waiting..... ready! (6s)
#   ✓ SearXNG running at http://localhost:4040

What the setup does

Creates ~/.hypersearchx/searxng/settings.yml with an optimised config
Pulls docker.io/searxng/searxng:latest
Starts container: docker run -d --name hsx-searxng --restart unless-stopped -p 4040:8080
Polls the JSON health endpoint until ready (up to 30 seconds)
Idempotent — safe to run multiple times (skips steps already done)

Container management

bash

# View logs
docker logs hsx-searxng -f

# Restart
docker restart hsx-searxng

# Stop
docker stop hsx-searxng

# Start (if stopped)
docker start hsx-searxng

# Remove and recreate
docker rm -f hsx-searxng && hsx setup --searxng

Enabled search engines

Engine	Category	Shortcut	Timeout
Google	General	`!g`	6s
Bing	General	`!b`	6s
DuckDuckGo	General	`!d`	6s
Brave	General	`!br`	6s
Wikipedia	General	`!w`	6s
StackOverflow	IT	`!so`	6s
GitHub	IT	`!gh`	6s
arXiv	Science	`!arx`	8s
Reddit	Social	`!re`	6s
HackerNews	Social	`!hn`	6s

Generated settings.yml

The auto-generated config is saved at ~/.hypersearchx/searxng/settings.yml. You can edit it freely — the container mounts it as a volume.

settings.yml (key sections)

server:
  secret_key: "auto-generated-64-hex-chars"
  limiter: false          # No rate limiting (local use)
  image_proxy: false

search:
  safe_search: 0
  default_lang: en
  formats:
    - html
    - json              # Required for HyperSearchX JSON API calls

outgoing:
  request_timeout: 6.0
  max_request_timeout: 10.0
  pool_connections: 100
  enable_http2: true

Manual Docker setup

If you prefer to set up SearXNG manually:

bash

# Create config directory
mkdir -p ~/.hypersearchx/searxng

# Generate a secret key
SECRET=$(openssl rand -hex 32)

# Create minimal settings.yml
cat > ~/.hypersearchx/searxng/settings.yml << EOF
use_default_settings: true
server:
  secret_key: "$SECRET"
  limiter: false
search:
  formats:
    - html
    - json
EOF

# Start the container
docker run -d \
  --name hsx-searxng \
  --restart unless-stopped \
  -p 4040:8080 \
  -v ~/.hypersearchx/searxng:/etc/searxng:rw \
  docker.io/searxng/searxng:latest

# Configure HyperSearchX to use it
hsx config set search.searxng_url http://localhost:4040

Using a remote SearXNG instance

bash

# Point to any public or private SearXNG instance
hsx config set search.searxng_url https://searx.example.com

# Or via environment variable
export SEARXNG_URL=https://searx.example.com

Note: Remote instances must have JSON format enabled in their settings (formats: [html, json]). Many public instances disable the JSON API to prevent abuse.

Troubleshooting

Issue	Fix
Container won't start	`docker logs hsx-searxng` — check for port conflicts
Port 4040 in use	Change with `hsx config set search.searxng_url http://localhost:4041` and re-run setup
JSON API disabled	Add `- json` under `search.formats` in settings.yml
No results from engine	Check Docker logs — engine may be rate-limited or blocked

Check status

bash

# Quick health check
hsx setup --check

# Or curl directly
curl "http://localhost:4040/search?q=test&format=json" | jq .number_of_results

Next steps

Configuration →

Full config.toml reference

Docker Setup →

Full stack deployment

Search API →

Use SearXNG-powered search

Quick Start →

Make your first request