# MiniSearch by felladrin: a self-hosted search engine with browser-side AI

> MiniSearch bundles SearXNG, a cross-encoder reranker and an optional in-browser LLM into one Docker container, so queries never need to leave your machine. The trade-off is that you maintain the container, and the AI quality depends on which model your hardware can actually run.

**felladrin/MiniSearch** — Minimalist web-searching platform with an AI assistant that runs directly from your browser. Demo: https://felladrin-minisearch.hf.space

- Repository: https://github.com/felladrin/MiniSearch
- Website: https://felladrin-minisearch.hf.space
- Stars: 598 · Forks: 74
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/felladrin-minisearch

## What MiniSearch solves, and who ends up running it

Most AI search products route your query through someone else's servers. MiniSearch takes the opposite position. The README describes it as "a self-hosted search engine with an AI assistant", and the AI can run entirely inside the browser tab, on GPU or CPU. That means no API key, no separate inference server, and no third party seeing the queries. The project targets people who already accept the maintenance cost of self-hosting in exchange for that property: engineers with a home server or a small VPS, privacy-conscious teams that want a shared internal search page, and anyone who wants to try a retrieval-augmented pipeline without signing up for a hosted model. It is not a search index. It does not crawl the web itself. Web results come from a bundled SearXNG instance, which is a metasearch aggregator, so the quality of what you get back depends on the upstream engines SearXNG queries, not on MiniSearch.

## The request path: SearXNG, a cross-encoder, then the model

The README's flow diagram splits the system into two halves. In the browser there is the search UI, an optional local model, and IndexedDB for history and cache. In the container there is the app server, SearXNG, and a reranker built on ONNX Runtime. A query goes to the app server, which asks SearXNG to aggregate results from multiple engines. The server then reranks them with a small cross-encoder model before returning them, and the browser caches the result locally. If the AI answer is enabled, the assistant reads the top results and writes a cited response, either from a model in the browser or from a backend you configured. Two details in that design are worth noting. The reranking happens server-side on every query, which is where the container earns its memory. And the browser cache plus IndexedDB storage means history, cached results and chats stay local, so clearing site data wipes them. The README states that retention is configurable.

## Installing MiniSearch and running a first query

The quickest path is the published image. The README gives a single command, and the container listens on port 7860.

```bash
docker run -p 7860:7860 ghcr.io/felladrin/minisearch
```

Open http://localhost:7860 and start searching. If you prefer Compose, the README shows this service block to add to your docker-compose.yml:

```yaml
services:
  minisearch:
    image: ghcr.io/felladrin/minisearch:latest
    ports:
      - "7860:7860"
```

To build from source instead, the README uses the production compose file:

```bash
git clone https://github.com/felladrin/MiniSearch.git
cd MiniSearch
docker compose -f docker-compose.production.yml up --build
```

One caveat the README raises itself: latest moves on every release, so it changes under you. To stay on a known build, it suggests pinning the digest, which always identifies the same image:

```bash
docker inspect --format '{{index .RepoDigests 0}}' ghcr.io/felladrin/minisearch:latest
docker run -p 7860:7860 ghcr.io/felladrin/minisearch@sha256:1a2b3c...
```

The README notes that the version the running instance reports, in the menu and under build on /status, tells you which commit it was built from. If you would rather not run a server at all, the README points to duplicating the Hugging Face Space, where environment variables can be set in the Space settings.

## Choosing an inference backend, and what each one costs you

MiniSearch does not force one model path. The .env.example file lists a DEFAULT_INFERENCE_TYPE with four documented values: browser for in-browser inference, openai for a remote OpenAI-compatible API, horde for AI Horde, and internal for the server-proxied API whose display name comes from INTERNAL_OPENAI_COMPATIBLE_API_NAME. The browser option uses Wllama, and WLLAMA_DEFAULT_MODEL_ID ships as littlelamb-290m. The README says the curated models range from 135M to 4B parameters and run on WebGPU where available and on CPU elsewhere, downloaded once and cached by the browser. That range is the real constraint. A 135M or 290M model will load quickly on modest hardware but will produce weaker answers than a hosted frontier model, and a 4B model may be slow or unusable without WebGPU. The remote option exists precisely for that gap: point it at Ollama, LM Studio, vLLM, llama.cpp server, or a hosted provider. The README also covers a middle case, where others can use your instance with your API key without seeing it, by configuring the INTERNAL_OPENAI_COMPATIBLE_API_* variables.

## Where MiniSearch is the wrong tool

The container builds SearXNG from source at a pinned commit, SEARXNG_COMMIT_SHA in the Dockerfile, and the README's own pinning advice implies the moving latest tag is a real operational concern. That is a maintenance surface you inherit. Upstream SearXNG changes, and the pinned commit is what you get until the project bumps it. The second limitation is the browser model ceiling. If your users are on machines without WebGPU, they fall back to CPU inference, and the small curated models are the only realistic option there. Anyone expecting answers comparable to a large hosted model should configure the OpenAI-compatible path instead, at which point the privacy argument narrows to whatever that endpoint logs. Third, MiniSearch does not index anything. It aggregates through SearXNG, so a query that no upstream engine surfaces cannot be answered, and the reranker can only reorder what came back. If you need a searchable corpus of your own documents, this is not that product.

## MiniSearch versus running SearXNG on its own

The obvious alternative is SearXNG by itself. MiniSearch contains a SearXNG instance, so the difference is what sits around it. Plain SearXNG returns a list of links and stops. MiniSearch adds a server-side cross-encoder reranker over those results, a browser cache, a local history with fuzzy search, pinning and full-session restore, and the optional assistant that reads the top results and writes an answer with citations. It also adds the client-side model machinery: Wllama, the Hugging Face tokenizer packages, and the ONNX reranker. If you already run SearXNG and only want a private front end, adding MiniSearch means adding a Node app server and an inference layer you may not need. If what you actually want is cited answers over web results without sending queries to a hosted search API, the reranker plus the assistant is the reason to pick MiniSearch over a bare SearXNG deployment.

## Licence, upgrades and the cost of staying current

MiniSearch is licensed under Apache-2.0, and the package.json repeats that identifier. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also carries notice and attribution obligations, and the bundled SearXNG is a separate project with its own licence terms that you should read before redistributing an image. That is a factual note, not legal advice. On upgrades, the README's digest-pinning advice is the practical mechanism: latest tracks releases, a digest does not, and the build reported on /status tells you which commit is running. The repository also carries renovate.json and a CI workflow, which is where dependency bumps appear, but the README does not document a rollback procedure, so plan your own by keeping the previous digest. Note that the last push to the repository was on 2026-09-10.

## Conclusion

Adopt MiniSearch if you want a private, self-hosted metasearch front end and are comfortable running a Docker container that builds SearXNG from a pinned commit. Skip it if you need a managed service, a large hosted model, or a search index you control. Before committing, run the container on port 7860, check /status for the build the instance reports, and confirm that the in-browser model you pick loads on your hardware under WebGPU or CPU.

## FAQ

### How do I make MiniSearch my browser's default search engine?

Add a custom search engine in your browser settings using the pattern http://localhost:7860/?q=%s, replacing the host with your instance's address. Your search term replaces %s.

### Can MiniSearch use my own models through an OpenAI-compatible API?

Yes. Open the menu, set AI Processing Location to Remote server (OpenAI-compatible API), then fill in the base URL and optionally an API key and a model name. If the model is left blank, it is picked from the ones the API lists.

### Can other people use my MiniSearch instance with my API key without seeing it?

Yes. The README states you can configure the INTERNAL_OPENAI_COMPATIBLE_API_* variables so the server proxies your own API without exposing its key. The .env.example file lists the base URL, key, model and display name variables for that internal API.

### Does MiniSearch need an API key to run?

No. The README states the AI can run entirely inside the browser tab, on GPU or CPU, so a working setup needs no API key and no separate inference server. An API key is only needed if you choose a remote OpenAI-compatible backend.

### Where does MiniSearch store my search history and chats?

The README states that search history, cached results and chats are stored in your browser and never leave your machine. The flow diagram shows them in IndexedDB, and retention is configurable.

## Sources

- [felladrin/MiniSearch on GitHub](https://github.com/felladrin/MiniSearch)
- [Issues](https://github.com/felladrin/MiniSearch/issues)
- [License: Apache-2.0](https://github.com/felladrin/MiniSearch/blob/main/LICENSE)
- [Project website](https://felladrin-minisearch.hf.space)
- [README](https://github.com/felladrin/MiniSearch/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/felladrin-minisearch