# Project pack: SearXNG @ 8137186

Facts about **SearXNG** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> SearXNG is a search engine you run yourself. When you search, it asks many search engines at once (Google, Bing, DuckDuckGo, Wikipedia and over 200 more), mixes the results and shows them without ads, profiling or tracking. It is also the private web-search engine behind many self-hosted AI helpers, such as Vane (Perplexica), Khoj, LibreChat and AnythingLLM, which can use it to look things up online.

## Version and source
- Repository: https://github.com/searxng/searxng
- Pinned commit: `81371861f67226091d1c4df2e3908a11d3b54eb9`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/searxng/searxng/archive/81371861f67226091d1c4df2e3908a11d3b54eb9.zip
- Official docs: https://docs.searxng.org
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/searxng/searxng bespoke-searxng
  cd bespoke-searxng
  git checkout --detach 81371861f67226091d1c4df2e3908a11d3b54eb9
  # Prepare development requirements and local configuration first.
  # Setup notes: developer instance on http://127.0.0.1:8888
  make run
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  mkdir -p ./searxng/core-config/ && cd ./searxng/ && curl -fsSL -O https://raw.githubusercontent.com/searxng/searxng/81371861f67226091d1c4df2e3908a11d3b54eb9/container/docker-compose.yml -O https://raw.githubusercontent.com/searxng/searxng/81371861f67226091d1c4df2e3908a11d3b54eb9/container/.env.example && cp .env.example .env && docker compose up -d # then open http://localhost:8080 (settings.yml appears in ./core-config/ on first start)
  ```

- Needs: Docker with Docker Compose, Very light, runs happily on a Raspberry Pi or small home server, For development, Python 3, Node.js and make (the Makefile sets up a virtualenv)
- Develop: `make run   # developer instance on http://127.0.0.1:8888`
- Test: `make test`
- Check/lint: `make test.pylint test.black`
- Stack: python, typescript (Flask, Jinja2, Granian, Vite). Difficulty for a non-developer with an AI: **easy**. Almost everything (name, engines, categories, safe search, theme, blocked or preferred websites) is a line in settings.yml, with no code changes. Code is a mature Python/Flask app with Jinja templates; changing it needs the repo's Makefile tooling and a careful eye on privacy.

## The project's own AI instructions
Read these in the repository before changing code: `AI_POLICY.rst`, `CONTRIBUTING.rst`.

## Customisation points (settings → extend → code)
- **instance-basics** [settings]: Name it, e.g. "Family Search", and set your own contact and privacy links. → `core-config/settings.yml → general (instance_name, contact_url, privacypolicy_url) and brand`
- **search-defaults** [settings]: Family-safe results, search suggestions, default language, and JSON output for AI apps. → `settings.yml → search (safe_search, autocomplete, default_lang, formats)`
- **engines** [settings]: Turn search engines on or off, prefer some over others, and give them ! shortcuts. → `settings.yml → engines (disabled, weight, shortcut); docs/admin/settings/settings_engines.rst`
- **hostnames** [settings]: Hide sites you never want to see, push favourites to the top, or rewrite links (e.g. YouTube to a privacy front-end). → `settings.yml → hostnames (replace, remove, low_priority, high_priority) for searx/plugins/hostnames.py`
- **look-and-preferences** [settings]: Light, dark or black theme, centred layout, default language, and lock settings so children can't change them. → `settings.yml → ui (theme_args.simple_style, center_alignment, results_on_new_tab, default_locale) and preferences.lock; or the Preferences page per browser`
- **plugins** [extend]: Calculator, unit converter, tracker-link remover, infinite scroll, or your own plugin. → `settings.yml → plugins (enable/disable); custom plugins as Python classes like those in searx/plugins/`
- **json-api** [extend]: Lets AI apps such as Vane, Khoj, LibreChat or AnythingLLM use your SearXNG for web search. → `/search?q=…&format=json (add json to search.formats; docs/admin/api.rst)`
- **theme-templates** [code]: Change the page layout and styling beyond the built-in options. → `searx/templates/simple/** and client/simple/src/** (build with make themes)`
- **engines-code** [code]: Add a new search source, e.g. your library catalogue or a hobby forum. → `searx/engines/*.py`

## Must keep working
- Privacy. No logging of searches or IP addresses, no tracking cookies, and results requested on the user's behalf.
- The JSON output format if other apps (Vane, Khoj, LibreChat, AnythingLLM) depend on it.
- Keep your changes in core-config/settings.yml with use_default_settings, so upstream defaults keep updating underneath.

## Staying updatable
settings.yml with use_default_settings: true keeps personal changes separate from upstream defaults, so updates are just a new image. SearXNG's AI_POLICY.rst requires disclosing all AI use, says AI must never be the main author of a pull request, and blocks people who send AI "slop". Keep AI-written changes in your own copy.

## Data, costs and safety
- Personal data: **no**. Stored in: Settings in ./core-config/settings.yml; cache in the core-data and valkey-data volumes. SearXNG does not keep a search history. There is little to back up apart from settings.yml (and any hostname lists next to it). Searches are not stored, but your server's address is what search engines see, and server logs may record requests if you turn them on.
- Service: Public search engines (Google, Bing, DuckDuckGo, Brave, Wikipedia, Qwant and many more) (required, free): Where the results come from. SearXNG asks them on your behalf, so they see your server, not you.
- Service: Valkey (bundled in the compose file) (optional, free, self-hosted): Cache and bot-protection data for the limiter on public instances.
- Setting `SEARXNG_VERSION`: Which image tag to run, e.g. latest or a dated release. Pin it to avoid surprise upgrades.
- Setting `SEARXNG_PORT`: Port to listen on (8080 in the container setup).
- Setting `SEARXNG_HOST`: Address to listen on, e.g. 127.0.0.1 to allow only this computer.
- Setting `SEARXNG_BASE_URL`: The public address of your instance, so links and the browser search shortcut work.
- Setting `SEARXNG_SECRET` (**secret**: the person enters it themselves, never in chat): Secret key for the instance. The container generates one on first start; set your own if you manage settings.yml yourself.
- Setting `SEARXNG_LIMITER`: true turns on bot protection, which you need if the instance is open to the internet.
- Setting `SEARXNG_PUBLIC_INSTANCE`: true enables extra protections meant for instances anyone can use.
- An open instance on the internet attracts bots and can get your server's address blocked by Google and others. Keep it private, or turn on SEARXNG_LIMITER and SEARXNG_PUBLIC_INSTANCE.
- Search engines see your server's address. On a home connection that is your household's address, so it hides who searched, not which household.
- SearXNG itself has no AI. When an AI app uses it, the app (not SearXNG) decides what is sent to an AI provider.
- Leave the generated secret key in settings.yml private, and pin SEARXNG_VERSION for predictable updates.

---

# Customising SearXNG

SearXNG is a mature Python (Flask) app. **Nearly everything is one file: `settings.yml`.** In the Docker setup it appears in `./core-config/settings.yml` on first start, beginning with `use_default_settings: true`, so you only write the lines you want to change and upstream defaults keep updating underneath. Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
Edit `core-config/settings.yml`, then `docker compose restart core`.
- **Name and links:** `general.instance_name`, `general.contact_url`, `general.privacypolicy_url`, `general.donation_url`.
- **Search defaults:** `search.safe_search` (0 off, 1 moderate, 2 strict), `search.autocomplete`, `search.default_lang`, and `search.formats` (add `json` for AI apps).
- **Engines:** under `engines:`, set `disabled: true/false`, `weight` (higher ranks higher) and `shortcut` (type `!wp cats` to search only Wikipedia). See `docs/admin/settings/settings_engines.rst`.
- **Websites to hide or promote:** the `hostnames:` block (`remove`, `low_priority`, `high_priority`, `replace`), used by the Hostnames plugin.
- **Look:** `ui.theme_args.simple_style` (auto, light, dark, black), `ui.center_alignment`, `ui.results_on_new_tab`, `ui.default_locale`.
- **Lock preferences:** `preferences.lock` stops people changing chosen options (e.g. safe search) on the Preferences page.
- **Tabs:** `categories_as_tabs` chooses which categories show as tabs.
- **Public instance protection:** `SEARXNG_LIMITER=true` and `SEARXNG_PUBLIC_INSTANCE=true` in `.env`.

## Level 2: Extend (no fork)
- **Plugins:** switch built-ins on or off under `plugins:` (calculator, unit converter, tracker-URL remover, infinite scroll, Tor check, DOI rewrite and more).
- **JSON API:** with `json` in `search.formats`, `http://localhost:8080/search?q=hello&format=json` returns results. Vane (Perplexica), Khoj, LibreChat and AnythingLLM can all use this for private web search.
- **Browser default:** SearXNG publishes an OpenSearch description, so browsers can add it as their default search engine.
- **External bangs:** `!!g` and friends jump straight to another site's search.

## Level 3: Code
Read upstream `CONTRIBUTING.rst` and `AI_POLICY.rst` first.

| Change | Where |
|---|---|
| New search source | `searx/engines/<name>.py` + an entry under `engines:` in `searx/settings.yml` |
| New plugin | `searx/plugins/<name>.py` (copy the pattern of e.g. `unit_converter.py`) |
| Page templates | `searx/templates/simple/**` |
| Styles and scripts | `client/simple/src/**`, built with `make themes` |
| Wording | `searx/templates/simple/**` and translations in `searx/translations/` (via Weblate) |
| Default settings | `searx/settings.yml` (but prefer your own `core-config/settings.yml`) |

## Running locally
- **Just use it:** download `container/docker-compose.yml` and `container/.env.example` at the pinned commit into a `searxng` folder with an empty `core-config/`, copy `.env.example` to `.env`, run `docker compose up -d`, and open http://localhost:8080.
- **Develop:**
  1. Clone the repo.
  2. Run `make run`. It creates a virtualenv and starts a developer instance on http://127.0.0.1:8888.
- **Check:** `make test` (lint, unit and robot tests), `make format` before committing.

## Pitfalls
- Keep `use_default_settings: true` at the top of your settings file. Without it you must copy every default yourself and miss upstream fixes.
- Some engines (especially Google) block busy or public instances. Spread searches across several engines.
- AI apps need `json` in `search.formats`; some (Vane) also want the Wolfram Alpha engine enabled.
- Don't turn on request logging if you care about privacy.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/searxng/8137186/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/searxng/8137186/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/searxng/8137186/r2/SKILL.md)