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

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, 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, 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, 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, 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.

# 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.

# 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.

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:

# 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.

Optional: Enable Semantic Search with Vector Embeddings

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

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. 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}