On this page
Set Up Self-Hosted SearXNG as Holon WebSearch Provider
Connect a self-hosted SearXNG meta-search instance to Holon as the local data plane backend for the WebSearch tool. By hosting SearXNG locally, your agents can perform technical research and web searches without requiring commercial cloud search API keys, while preventing search terms from leaving your infrastructure. This setup is ideal for privacy-conscious environments or deployments that need predictable, zero-marginal-cost web discovery.
This guide is based on live, account-level self-hosted testing and end-to-end verification across isolated Holon instances. It covers single-container deployment with network tuning, Holon provider configuration, positive and negative test evidence, and troubleshooting. For general web tool workflows and security boundaries, see Fetch and search web content and the Web tools reference.
Prerequisites
- A host machine with Docker installed and running.
- Holon 0.59.0 or higher (with built-in
kind = "searxng"web provider support). - Official SearXNG Docker image (tested with
searxng/searxng:2026.11.9-57ff753ad). - Outbound network connectivity from the host (for SearXNG to query upstream public search engines).
Step 1: Deploy SearXNG (Docker)
1. Prepare settings.yml
Create a local directory and write the minimal working configuration. Explicitly enable JSON API format output and narrow the upstream engine list based on network reachability:
# settings.yml
# Bind to loopback only; disable rate limiter for single-user local setups
use_default_settings:
engines:
keep_only:
- bing
- bing news
- baidu
engines:
- name: bing
disabled: false
- name: bing news
disabled: false
- name: baidu
disabled: false
server:
secret_key: "<generate with: openssl rand -hex 24>"
limiter: false
image_proxy: false
search:
formats:
- html
- json # Required: Holon's searxng provider requires format=json; omitting this causes HTTP 403
timeout: 8.0
# Shorten penalty periods so temporary network blips do not suspend healthy engines
ban_time_on_fail: 5
max_ban_time_on_fail: 30
Key configuration considerations:
search.formatsmust includejson: SearXNG disables JSON API output by default. Missing this setting causes all API calls to fail with an HTTP 403 HTML error page, which is the most frequent onboarding mistake.- Prune active engines: Use
use_default_settings.engines.keep_onlyto select reliable engines and override their state withdisabled: false. Public engines have vastly different reachability profiles across datacenter and cloud networks; keeping hundreds of default engines enabled causes slow queries and excessive unresponsive engine warnings. - Avoid unconfigured keyed engines: Engines marked
inactive: true(such as Marginalia) require API keys to initialize. Because this guide focuses on a zero-credential setup, leave them unconfigured.
2. Start the container
Launch the container using a pinned image tag, host networking, and strict loopback binding:
docker run -d --name searxng \
--network host \
-e GRANIAN_HOST=127.0.0.1 \
-e GRANIAN_PORT=8888 \
-v "$PWD/settings.yml:/etc/searxng/settings.yml:ro" \
searxng/searxng:2026.11.9-57ff753ad
Network and security details:
- Why host networking is recommended: In many datacenter network environments, Docker's default bridge NAT network can introduce packet drops and timeouts when connecting to certain upstream engines (such as Bing), even when the host itself reaches them without issue (1.1s–1.9s latency). Using
--network hostbypasses the bridge NAT and uses the host's network stack directly, eliminating "healthy instance but zero search results" issues. - Strict loopback binding: Under host networking, applications may bind to
*:8888by default. Because the official image uses Granian as its ASGI entrypoint, pass-e GRANIAN_HOST=127.0.0.1to restrict binding to the loopback interface (the legacySEARXNG_BIND_ADDRESSvariable is ignored by Granian). Verify binding withss -ltn | grep 8888. If bridge networking is mandatory, use-p 127.0.0.1:8888:8088to constrain exposure, but monitor for upstream packet loss.
Verify the JSON API with a quick smoke test:
curl -s "http://127.0.0.1:8888/search?q=test&format=json" | grep -o '"results":\['
A matching output indicates that SearXNG is responding with valid JSON.
Step 2: Configure Holon
You can configure Holon via the CLI or edit config.json directly.
Option A: Use the Holon CLI
Run the following commands in your terminal:
# Register the SearXNG provider endpoint
holon config set web.providers.searxng.kind searxng
holon config set web.providers.searxng.base_url "http://127.0.0.1:8888"
# Switch the default WebSearch provider to searxng
holon config set web.search.enabled true
holon config set web.search.provider searxng
Option B: Edit config.json directly
Add the provider and routing definitions under the web section of your Holon configuration:
{
"web": {
"search": {
"enabled": true,
"provider": "searxng",
"mode": "single"
},
"providers": {
"searxng": {
"kind": "searxng",
"base_url": "http://127.0.0.1:8888"
}
}
}
}
Provider features:
- Zero credential management: The
searxngprovider does not need acredential_profileor API key. - Path prefix support: The
base_urlsupports path prefixes (such ashttps://internal.example.com/searxng/); Holon automatically appends/searchwhile preserving the prefix. - Consistent result normalization: When an agent invokes
WebSearch, Holon standardizes the result count usingmax_results(defaulting to 5). Titles, URLs, snippets, and citations follow the exact same schema as cloud providers.
Step 3: End-to-end verification
Positive test cases
Instruct your agent in conversation:
Use WebSearch to search for "Holon runtime agent", and summarize the top 3 results with their source URLs.
The agent invokes WebSearch { query: "Holon runtime agent", max_results: 5 }. Verified test observations:
- JSON API smoke test: Tested across GitHub repositories, technical documentation, and news queries; each returned 10 structured items with ~0.6s response latency.
- Isolated instance routing: Verified on an isolated
HOLON_HOMEinstance configured withkind = "searxng". WebSearch correctly routed queries to the local instance and returned 5 structured results including official repositories and documentation. - Multi-query stability: Executed 8 consecutive queries across distinct technical domains; 8 out of 8 succeeded, yielding 10–11 aggregated items per query (isolated upstream bot-detection challenges like Baidu CAPTCHAs degraded gracefully without failing the overall query).
- Search-and-fetch closed loop: The agent followed up with
WebFetchon the returned URLs, successfully extracting page text, version numbers, and documentation tables. - Quality comparison: Compared against commercial cloud providers (such as Brave) on the same queries, self-hosted SearXNG delivered broader domain diversity and sufficient precision for engineering workflows.
Empty results and error responses
Holon distinguishes a valid empty result from a request or parsing error:
| Scenario | SearXNG server behavior | Holon agent observation |
|---|---|---|
search.formats lacks json | HTTP 403 Forbidden (HTML error page) | Reports network_failed with HTTP 403 Forbidden, retryable: true, and a hint to check whether search.formats includes json |
base_url unreachable or port closed | Connection refused | Reports network_failed with full request URL and retry suggestions |
| Valid empty results (for example, when all upstream engines time out) | HTTP 200 with {"results": []} | Succeeds with zero results |
Invalid JSON, missing or non-array results, or a non-empty array with no usable entries | HTTP 200 with an invalid or unusable body | Reports parse_failed |
Note: In fallback mode, Holon stops at the first successful provider response, even if it contains zero results. An empty result alone does not mean the instance or its upstream engines failed.
Step 4: Troubleshooting
- WebSearch reports
network_failedwithHTTP 403 Forbidden: Check whethersearch.formatsin the instance'ssettings.ymlincludesjson. If you manage the instance and change this setting, restart the container. If JSON is already enabled, investigate other reasons for the 403. - WebSearch reports
network_failedwith connection refused: Holon cannot reach the configuredbase_url. Runcurl -s "http://127.0.0.1:8888/search?q=test&format=json"on the host to verify container health, and check host firewall rules. - WebSearch succeeds with zero results when you expect matches:
Check the raw SearXNG response for
unresponsive_engines. If it shows timeouts or challenges, retry the query or enable additional engines. If timeouts persist, check for container networking issues and reviewsearch.timeoutandban_time_on_failinsettings.yml. - Intermittent empty results:
Single-engine suspension caused by timeout penalties. Enable at least two independent upstream engines in
keep_only(such as Bing alongside a secondary engine) to provide redundancy.
Step 5: Known limitations
- Datacenter IP reachability varies by engine: Public cloud and datacenter IP blocks are frequently blocked at the TLS handshake level or heavily rate-limited by privacy search engines (such as DuckDuckGo, Brave, or Startpage), while Baidu may trigger CAPTCHAs. In zero-credential setups, Bing-family engines offer the most reliable uptime. If additional engines are required, consider services with official API keys (such as Marginalia) and configure credentials in
settings.yml. - Windowed failure on single-engine setups: If only one engine is active and it experiences a temporary timeout, SearXNG suspends it, causing all subsequent queries to return empty results until the penalty expires. Always configure at least two independent engines in production.
- Language coverage depends on active engines: General engines like Bing cover both English and Chinese technical sources well. For niche locales or regional queries, explicitly enable regional engines.
Step 6: Cleanup
To shut down and remove the SearXNG deployment:
# Stop and remove the container
docker rm -f searxng
# Remove any unused anonymous volumes
docker volume ls -q | grep searxng | xargs -r docker volume rm
To switch Holon back to another search provider:
holon config set web.search.provider duckduckgo
See also
- Fetch and search web content guide — Trade-offs between search and fetch, and handling untrusted content
- Web tools reference — Full parameter and provider inventory for WebFetch, WebSearch, and XSearch
- Connect external events guide — Wake agents using webhooks and external triggers
