Self-Hosting

Self-Hosting with Docker

Run HyperSearchX on your own infrastructure. The entire stack runs in Docker Compose: the Rust API, SearXNG search backend, and SQLite database.

No request limits: Self-hosted deployments have no API quotas. You only pay for your own server costs.

Prerequisites

Docker Engine 24+ and Docker Compose v2
2 GB RAM minimum (4 GB recommended)
Linux, macOS, or Windows with WSL2

Quick start

bash

# Clone the repository
git clone https://github.com/zuhabul/hypersearchx.git
cd hypersearchx

# Copy and configure environment
cp .env.example .env
# Edit .env to set HSX_ADMIN_SECRET and other settings

# Start the stack
docker compose up -d

# Verify it's running
curl http://localhost:3050/health

Docker Compose configuration

docker-compose.yml

version: "3.9"

services:
  hsx-api:
    image: ghcr.io/zuhabul/hypersearchx:latest
    ports:
      - "3050:3050"
    environment:
      - HSX_ADMIN_SECRET=${HSX_ADMIN_SECRET}
      - SEARXNG_URL=http://searxng:8080
      - DATABASE_PATH=/data/hsx.db
    volumes:
      - hsx-data:/data
    depends_on:
      - searxng
    restart: unless-stopped

  searxng:
    image: searxng/searxng:latest
    volumes:
      - ./searxng:/etc/searxng
    restart: unless-stopped

volumes:
  hsx-data:

Environment variables

Variable	Required	Description
`HSX_ADMIN_SECRET`	Yes	Admin API secret (min 32 chars). Generate: `openssl rand -hex 32`
`SEARXNG_URL`	Yes	URL of your SearXNG instance
`DATABASE_PATH`	No	SQLite database path. Default: `~/.hypersearchx/hsx.db`
`HSX_PORT`	No	API port. Default: `3050`
`HSX_LOG_LEVEL`	No	`debug`, `info`, `warn`, `error`. Default: `info`
`ALLOWED_ORIGINS`	No	Comma-separated CORS origins. Default: none (API only)

Creating your first API key

After the stack is running, create an API key using the admin secret:

bash

curl -X POST http://localhost:3050/v1/admin/keys \
  -H "X-Admin-Secret: your_admin_secret_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "tier": "unlimited"}'

json

{
  "key": "hsx_4626d3fc3fd6693aaaf2d8f5fd084a71...",
  "id": "key_abc123",
  "name": "My App",
  "tier": "unlimited",
  "created_at": "2025-06-20T14:30:00Z"
}

Building from source

bash

# Install Rust (if not installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/zuhabul/hypersearchx.git
cd hypersearchx
cargo build -p hsx-cli --release

# Run
HSX_ADMIN_SECRET=your_secret \
SEARXNG_URL=http://localhost:8080 \
  ./target/release/hsx serve --port 3050

Reverse proxy with nginx

nginx.conf

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /etc/ssl/certs/yourdomain.crt;
    ssl_certificate_key /etc/ssl/private/yourdomain.key;

    location / {
        proxy_pass http://localhost:3050;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 90s;
    }
}

Updating

bash

# Pull latest image and restart
docker compose pull
docker compose up -d

Next steps

Quick Start →

Make your first API call

Source code and issues