SEARXNG ยท PRIVACY SEARCH ยท HOME ASSISTANT ADD-ON

SearXNG in Indigo Glass.

Operations wiki for the SearXNG Home Assistant Add-on: installation, settings.yml configuration, JSON API for automations and troubleshooting.

Add-on Slugsearxng
Web UIhttp://homeassistant.local:8080
AccessHA Ingress + direct
Upstream Imagesearxng/searxng

โšก Minimum Run Path

Install, start, open via sidebar or direct URL.

Web UI: http://homeassistant.local:8080
Config: addon_configs/_searxng/settings.yml

๐Ÿ” JSON API

Use SearXNG from HA automations via REST command.

GET http://localhost:8080/search?q=query&format=json
๐Ÿ 

Home

Overview

#home

SearXNG is a privacy-respecting metasearch engine that aggregates results from 70+ search engines โ€” no tracking, no profiles. This add-on wraps the official searxng/searxng image with HA Ingress support and a custom.sh hook.

#Wiki Pages

PagePurpose
InstallationAdd repository, install, start.
ConfigurationAdd-on options and settings.yml.
JSON APIUse SearXNG from HA automations.
TroubleshootingIngress, blank page, search engines.

#Minimum Operating Model

HA Ingress โ†’ SearXNG Web UI :8080
SearXNG    โ†’ aggregates search engines (outbound)
Config     โ†’ addon_configs/<SLUG>_searxng/settings.yml
๐Ÿš€

Installation

Install the Add-on

#installation

#Step 1 โ€” Add Repository

  1. Open Home Assistant.
  2. Go to Settings โ†’ Add-ons โ†’ Add-on Store.
  3. Open โ‹ฎ โ†’ Repositories.
  4. Add:
https://github.com/pol4rfuchs/ha-apps

#Step 2 โ€” Install

  1. Search for SearXNG in the Add-on Store.
  2. Click Install.

#Step 3 โ€” Start

  1. Enable Start on boot.
  2. Click Start.
  3. Open via Open Web UI button or the HA sidebar.
โš™๏ธ

Configuration

Options & settings.yml

#configuration

#Add-on Options

OptionDefaultDescription
set_base_url_for_ingresstrueAuto-sets SEARXNG_BASE_URL to the HA Ingress URL. Disable only if using an external reverse proxy.

#settings.yml

After the first start, the settings file is written to:

addon_configs/<SLUG>_searxng/settings.yml

Edit it via the File Editor add-on. Changes apply after restarting the add-on.

Full reference: docs.searxng.org

#custom.sh Hook

Runs before SearXNG starts. Useful for patching settings or activating plugins:

addon_configs/<SLUG>_searxng/custom.sh
#!/bin/sh
# Example: force safe search
sed -i 's/safe_search: 0/safe_search: 1/' /etc/searxng/settings.yml
๐Ÿ”Œ

JSON API

Use from HA Automations

#api

SearXNG exposes a JSON search API usable from HA automations and scripts.

#Endpoint

http://homeassistant.local:8080/search?q=your+query&format=json

#Home Assistant Integration

# configuration.yaml
rest_command:
  searxng_search:
    url: "http://localhost:8080/search?q={{ query }}&format=json"
    method: GET

#Limit to Specific Engines

http://localhost:8080/search?q=test&engines=google,bing&format=json
๐Ÿ’พ

Persistence

Config & Data

#persistence
addon_configs/<SLUG>_searxng/
โ”œโ”€โ”€ settings.yml    # SearXNG configuration
โ””โ”€โ”€ custom.sh       # Optional pre-start hook
The addon_configs directory is preserved across add-on updates. HA backups include it.
๐Ÿ› ๏ธ

Troubleshooting

Known Symptoms & Fixes

#troubleshooting
SymptomCauseFix
Sidebar shows blank pageIngress URL issue.Use direct URL: http://HA-IP:8080
Settings not appliedAdd-on not restarted.Restart the add-on after editing settings.yml.
Search returns no resultsEngine rate-limited or blocked.Check engine list in settings.yml; some engines block automated queries.
Ingress URL wrongBase URL not set.Enable set_base_url_for_ingress: true.
custom.sh not runningNot executable.Add chmod +x call or check script syntax.