Self-Hosting

Configuration Reference

HyperSearchX is configured via a TOML file at ~/.hypersearchx/config.toml. Every setting has a sensible default — the file is optional and created automatically on first run. You can also override any setting with environment variables.

Auto-generated: Run hsx setup to create a pre-configured instance with Chrome and SearXNG already set up.

Full config.toml reference

~/.hypersearchx/config.toml

# HyperSearchX Configuration
# Location: ~/.hypersearchx/config.toml
# All values shown are defaults unless noted.

[search]
# SearXNG instance URL for federated search backbone.
# Set by: hsx setup --searxng
# Default: none (uses direct HTTP scrapers)
searxng_url = "http://localhost:4040"

# Maximum parallel search backends to query simultaneously.
max_concurrent_backends = 5

# Per-backend timeout in seconds.
backend_timeout_secs = 10

# Default number of results per backend.
results_per_backend = 10

[extract]
# Maximum page size to download (bytes). Default: 5 MB.
max_page_bytes = 5_242_880

# Default detail tier: key_facts | summary | detailed | complete
default_tier = "summary"

# Default token budget (overrides tier if set).
# default_token_budget = 1000

[headless]
# Path to Chrome/Chromium binary.
# Set by: hsx setup --headless
# Auto-detected from: $HSX_CHROME_PATH env, this field, hsx-managed, system paths.
# chrome_path = "/home/user/.hypersearchx/chromium/chrome-linux64/chrome"

[cache]
# SQLite cache database path.
db_path = "~/.hypersearchx/cache.db"

# Cache TTL for search results (seconds). Default: 1 hour.
search_ttl_secs = 3600

# Cache TTL for extracted content (seconds). Default: 24 hours.
extract_ttl_secs = 86400

# Maximum cache database size (MB). Default: 500 MB.
max_size_mb = 500

[intelligence]
# Enable Persistent Intelligence Engine (PIE) — cross-session learning.
enabled = true

# SQLite database for intelligence data.
db_path = "~/.hypersearchx/intelligence.db"

[token]
# Default token budget for extractions.
default_budget = 1000

# Maximum allowed token budget.
max_budget = 20000

[http]
# HTTP connection pool size per host.
pool_connections = 10

# Request timeout (seconds).
timeout_secs = 30

# Maximum redirects to follow.
max_redirects = 10

# User-agent string.
user_agent = "HyperSearchX/1.0"

[logging]
# Log level: trace | debug | info | warn | error
level = "info"

# Log format: json | pretty
format = "pretty"

Environment variable overrides

Every config value can be overridden with an environment variable using theHSX_ prefix and underscores replacing dots:

Environment Variable	Config key	Example
`HSX_CHROME_PATH`	`headless.chrome_path`	`/usr/bin/chromium`
`SEARXNG_URL`	`search.searxng_url`	`http://localhost:4040`
`HSX_LOG_LEVEL`	`logging.level`	`debug`
`HSX_PORT`	API server port	`3050`
`HSX_ADMIN_SECRET`	Admin authentication key	(32+ char secret)

Configuration precedence

Environment variables — highest priority, always win
config.toml — user-specific settings
Built-in defaults — lowest priority, always present

Using hsx config commands

bash

# View all current settings
hsx config

# Get a specific value
hsx config get search.searxng_url

# Set a value
hsx config set search.searxng_url http://localhost:4040

# Open config file in $EDITOR
hsx config edit

Multiple environments

Use environment variables to switch between configurations without editing the file:

bash

# Development (local SearXNG)
SEARXNG_URL=http://localhost:4040 hsx search "rust async"

# Production (remote instance)
SEARXNG_URL=https://search.yourdomain.com hsx search "rust async"

Next steps

Docker Setup →

Full Docker Compose stack

SearXNG Integration →

Configure search backbone

Authentication →

API key management

Quick Start →

Make your first request