# How to Set Up Hister as a Self-Hosted Search Engine: Complete Installation Guide

> Install Hister as a self-hosted search engine using a single binary. Run the local server and connect the browser extension to index pages locally with an SQLite database.

- Repository: [Adam Tauber/hister](https://github.com/asciimoo/hister)
- Tags: getting-started
- Published: 2026-09-01

---

**You can set up Hister as a self-hosted search engine by installing the single binary, running `./hister listen` to start the local server on `127.0.0.1:4433`, and connecting the browser extension to index visited pages while keeping all data in a local SQLite database.**

Hister is a privacy-first, open-source personal search engine developed by asciimoo/hister that indexes web pages and local files without sending data to third parties. Setting up Hister as a self-hosted search engine gives you full control over your search index and queries, storing everything locally in SQLite with optional semantic search capabilities. This guide walks through the complete installation and configuration process based on the actual source implementation.

## Understanding Hister's Architecture for Self-Hosting

Before installing, you need to understand the three core components that work together in the self-hosted architecture:

### The Go HTTP Server

The **Server** is a Go HTTP service defined in the main package that stores documents, query indexes, and optional vector embeddings. According to [`hister.go`](https://github.com/asciimoo/hister/blob/main/hister.go), the entry point parses sub-commands like `listen`, `search`, and `import` before delegating to specific handlers. The server reads its runtime configuration from [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go), which validates settings and creates a default configuration via `CreateDefaultConfig` when no file exists.

### Browser Extensions for Content Capture

The **Browser extensions** for Chrome and Firefox capture page content and favicons, then push them to your local server. As documented in [`webui/website/src/content/docs/quickstart.md`](https://github.com/asciimoo/hister/blob/main/webui/website/src/content/docs/quickstart.md), these extensions never transmit data to third-party sites; they only communicate with the `BaseURL` you configure. The extension automatically detects the server address during setup.

### Client Interfaces

The **Clients** include a web UI accessible at the server address, a terminal UI (TUI) implemented in [`cmd/tui/tui.go`](https://github.com/asciimoo/hister/blob/main/cmd/tui/tui.go), and the command-line client (`hister`). The TUI handles keyboard navigation using hotkeys defined in the configuration file, allowing you to search and open results without leaving the terminal.

## Step 1: Install the Hister Binary

Download the pre-compiled executable for your operating system from the latest release. The binary contains the server, TUI, and CLI tools in a single file.

```bash

# Download the latest release for your platform

curl -L -o hister https://github.com/asciimoo/hister/releases/latest/download/hister-$(uname -s)-$(uname -m)

# Make the binary executable

chmod +x hister

# Optional: move to a directory in your PATH

sudo mv hister /usr/local/bin/

```

## Step 2: Configure and Start the Server

Initialize the server by running the `listen` command. This creates the data directory and SQLite database automatically.

```bash

# Start the server in the foreground

./hister listen

```

By default, the server launches on `127.0.0.1:4433` and creates a data directory at `~/.config/hister` containing `db.sqlite3`. The server auto-detects its address and updates the `BaseURL` accordingly using the `Config.UpdateBaseURL` method found in [`config/config.go`](https://github.com/asciimoo/hister/blob/main/config/config.go).

If you need to customize the listening address, edit the YAML configuration file located at `~/.config/hister/config.yml` (or your OS-specific XDG config path). When this file is missing, Hister falls back to the built-in defaults defined in `CreateDefaultConfig`.

## Step 3: Set Up Browser Extensions for Web Indexing

Install the official Chrome or Firefox extension to capture visited pages. During installation, the extension automatically points to your server's base URL (`http://127.0.0.1:4433` by default).

Once connected, the extension forwards the full content of newly visited pages to the server for indexing. All processing happens locally; no browsing data leaves your machine.

## Step 4: Index Local Files and Browser History

To index existing local documents or browser history exports, use the `import` command:

```bash

# Import a local directory (recursive)

./hister import --dir ~/Documents

# The importer respects the rules defined in config.Indexer.Directories

```

This creates searchable records in the same SQLite database used for web content.

## Step 5: Search Your Indexed Data

You can query your index through multiple interfaces:

- **Web UI**: Open `http://127.0.0.1:4433` in any browser to run searches, define indexing rules, and manage imported data.
- **Terminal UI**: Run `./hister search "your query"` to launch the TUI. Navigate results using **Alt-j** and **Alt-k**, then press **Enter** to open items. Key bindings are configurable via `Config.Hotkeys` in [`cmd/tui/tui.go`](https://github.com/asciimoo/hister/blob/main/cmd/tui/tui.go).

## Optional: Enable Semantic Search with Vector Embeddings

For AI-powered similarity search, enable semantic indexing by editing `~/.config/hister/config.yml`:

```yaml
semantic_search:
  enable: true
  embedding_endpoint: http://localhost:11434/v1/embeddings
  embedding_model: qwen3-embedding:8b

```

When enabled, the server stores document embeddings in the same SQLite file using the vector extension implemented in [`server/vectorstore/sqlitevec/sqlite-vec.c`](https://github.com/asciimoo/hister/blob/main/server/vectorstore/sqlitevec/sqlite-vec.c). It utilizes HNSW (Hierarchical Navigable Small World) graphs for fast similarity lookup, allowing you to find conceptually related content beyond exact keyword matches.

## Summary

- **Single binary deployment**: Hister distributes as one executable containing the server, TUI, and CLI tools.
- **Default local hosting**: The server binds to `127.0.0.1:4433` and stores data in `~/.config/hister/db.sqlite3`.
- **Configuration management**: Settings live in a YAML file that defaults to XDG config paths, with `CreateDefaultConfig` providing fallback values.
- **Privacy-first indexing**: Browser extensions communicate only with your local instance, never with external services.
- **Extensible search**: Enable `semantic_search` in the config to use vector embeddings and HNSW similarity search via the SQLite vector extension.

## Frequently Asked Questions

### Where does Hister store my search index and configuration?

Hister stores the SQLite database (`db.sqlite3`) and [`config.yml`](https://github.com/asciimoo/hister/blob/main/config.yml) in `~/.config/hister` by default, following XDG Base Directory specifications. You can verify the exact path by checking the startup logs when running `./hister listen`, as the server logs its data directory location during initialization.

### Does the browser extension send data to any third parties?

No. The browser extensions only communicate with the `BaseURL` you configure (default `http://127.0.0.1:4433`). As implemented in the extension manifest and documented in the quickstart guide, the code explicitly prevents sending data to external servers, ensuring your browsing history remains strictly local to your self-hosted instance.

### What are the system requirements for enabling semantic search?

Semantic search requires an external embeddings service compatible with the OpenAI API format, such as Ollama running locally. You must set `semantic_search.enable: true` and configure `embedding_endpoint` in your [`config.yml`](https://github.com/asciimoo/hister/blob/main/config.yml). The server uses the `sqlite-vec` C extension for vector storage, which is included in the binary and maintains embeddings within the same `db.sqlite3` file without requiring additional database software.

### Can I run Hister on a remote server instead of localhost?

Yes. While the default configuration binds to `127.0.0.1:4433`, you can modify the listening address in [`config.yml`](https://github.com/asciimoo/hister/blob/main/config.yml) or via environment variables. When you change the listen address, the `Config.UpdateBaseURL` function automatically updates the `BaseURL` used by browser extensions. For remote servers, ensure you configure appropriate firewall rules and consider enabling HTTPS for secure communication between clients and the server.