Configuration Reference

Hister is configured via a YAML file. It selects a primary config path using this precedence:

1. The path supplied with --config.
2. The path in HISTER_CONFIG, when --config is not supplied.
3. ./config.yml in the current working directory.

If the selected primary path does not exist, Hister searches the platform paths below and uses the first config file it finds.

Default Config Locations

Linux (respects $XDG_CONFIG_HOME):

• $XDG_CONFIG_HOME/hister/config.yml if $XDG_CONFIG_HOME is set, otherwise ~/.config/hister/config.yml
• ~/.histerrc (legacy, deprecated)

macOS (respects $XDG_CONFIG_HOME):

• $XDG_CONFIG_HOME/hister/config.yml if $XDG_CONFIG_HOME is set, otherwise ~/Library/Preferences/hister/config.yml
• ~/Library/Application Support/hister/config.yml (backwards compatible)
• ~/.histerrc (legacy, deprecated)
• ~/.config/hister/config.yml (legacy)

Windows (respects environment variables):

• %LOCALAPPDATA%\hister\config.yml (recommended)
• $XDG_CONFIG_HOME\hister\config.yml (if $XDG_CONFIG_HOME is set)
• %APPDATA%\hister\config.yml (fallback)
• ~\.histerrc (legacy, deprecated)
• ~\.config\hister\config.yml (legacy)

If you have a legacy ~/.histerrc file and Hister finds it, you’ll see a deprecation warning suggesting you move it to the recommended location.

Creating a Config File

Generate a config file with default values:

hister create-config ~/.config/hister/config.yml

Or use your platform’s recommended location:

# Linux
hister create-config ~/.config/hister/config.yml

# macOS
hister create-config ~/Library/Preferences/hister/config.yml

# Windows
hister create-config %LOCALAPPDATA%histerconfig.yml

You can also specify a custom config location using the --config flag:

hister listen --config /path/to/my/config.yml

Important: Restart the Hister server after modifying the configuration file.

Full Configuration

Use the configuration generated by your installed Hister version instead of copying a static example. Print the complete configuration with all current default values:

hister create-config

To create the configuration file directly, pass its destination path:

hister create-config /path/to/config.yml

app Section

server Section

Database Backends

Hister supports SQLite (default) and PostgreSQL.

The server.database value determines which backend is used:

• If the value contains = it is treated as a PostgreSQL DSN.
• Otherwise it is treated as an SQLite filename relative to app.directory.

SQLite (default)

server:
  database: 'db.sqlite3'

PostgreSQL

server:
  database: 'host=localhost user=hister password=hister dbname=hister port=5432 sslmode=disable TimeZone=Europe/Budapest'

Hister uses the standard PostgreSQL DSN key=value format. Adjust host, user, password, dbname, port, sslmode, and TimeZone to match your setup.

Semantic Search

Hister can augment keyword search with vector similarity search. When enabled, each indexed document gets a metadata vector containing its title, URL, specific extractor type when available, language, author, description, and topic metadata. Document text is split into overlapping structural chunks with compact title and language context, and each chunk is converted to a floating point vector by an external embedding model. The vectors are stored alongside the main index. At search time the query is also embedded and the closest chunks are retrieved, then merged with keyword results and reranked.

Semantic search is opt-in and disabled by default. It requires an OpenAI-compatible embeddings endpoint such as Ollama, a local llama.cpp server, or the OpenAI API itself.

Connection and Model

Chunking and Input

Retrieval

Processing

Vector Storage Backends

The vector store backend is chosen automatically based on server.database:

• SQLite (default) stores vectors in a separate vectors.sqlite3 file in the same directory as the main database, using the sqlite-vec extension. No extra setup required.
• PostgreSQL stores vectors in the same database as the main data using the pgvector extension. Hister uses an HNSW index with the vector type, which supports at most 2000 dimensions. Make sure pgvector is installed and enabled (CREATE EXTENSION vector;) before starting Hister.

Example

semantic_search:
  enable: true
  embedding_endpoint: 'http://localhost:11434/v1/embeddings'
  embedding_model: 'nomic-embed-text'
  embedding_timeout: 300
  dimensions: 768
  max_context_length: 512
  chunk_overlap: 50
  max_embedding_batch_size: 8
  query_prefix: 'search_query: '
  document_prefix: 'search_document: '
  similarity_threshold: 0.5
  result_limit: 10
  semantic_weight: 0.4
  max_embedding_concurrency: 2
  # api_key: 'sk-...'            # required for hosted providers
  # headers: {}                  # extra HTTP headers for proxies or custom auth

The example above uses nomic-embed-text via Ollama, which produces 768-dimensional vectors and fits well in a 512-token context window. The query_prefix and document_prefix values shown are the ones recommended by the Nomic model. Other models use different conventions: "query: " / "passage: " for E5 and BGE families (this is also the built-in default for query_prefix), "Represent this sentence for searching relevant passages: " for GTE. Check your model’s documentation for the expected prefix strings. Set both to "" for models that do not use prefixes (such as OpenAI text-embedding-3-*).

TUI Settings

TUI settings are configured in a separate tui.yaml file located in the same directory as your main config file. This file is automatically created with default values when you first run hister search.

Theme Settings

Built-in themes: catppuccin-frappe, catppuccin-latte, catppuccin-macchiato, catppuccin-mocha, dracula, gruvbox, gruvbox-light, material-lighter, nord, nord-light, one-light, rose-pine, rose-pine-dawn, solarized-light, tokyonight, and tomorrow.

indexer Section

Directory Entry

Each entry in directories is an object with the following keys:

When multiple filters are specified, they are applied in order: excludes first, then filetypes, then patterns. A file must pass all specified filters to be indexed. When a filter is omitted, it is not applied (all files pass).

Local Directory Indexing

The indexer.directories option lets you index local files so they appear alongside your browser history in search results. You do not need to run hister import file for configured directories that the server can access. After changing this configuration, restart the Hister server. It scans the directories automatically at startup, then a file watcher monitors them so new and modified files are indexed without another restart.

indexer:
  directories:
    - path: '~/notes'
      filetypes: ['txt', 'md']
      patterns: ['doc_*']
      excludes: ['*secret*']
    - path: '~/Documents/wiki'
      label: 'wiki'
    - path: '/path/to/project'
      label: 'project'
      filetypes: ['go', 'py', 'js']

Set label on a directory to apply the same searchable label to every file indexed from it. Changing a nonempty configured label updates existing files during the next startup scan, even when their contents have not changed. Leaving it empty preserves labels assigned manually.

User-scoped directories

When user_handling is enabled, you can scope indexed files to specific users using the user field. Files in a user-scoped directory are only visible to that user in search results. Global directories (no user set) are visible to all users.

indexer:
  directories:
    - path: '/nextcloud/notes/alice'
      user: 'alice'
      filetypes: ['txt', 'md']
    - path: '/nextcloud/notes/bob'
      user: 'bob'
      filetypes: ['txt', 'md']
    - path: '/shared/docs'
      # no user = global, visible to all
      filetypes: ['pdf', 'docx']

Visibility rules:

• A user sees files from directories where user == username plus global directories (user empty or unset) plus their own web documents
• Admins have the same visibility as regular users (no special access to other users’ files)
• Unauthenticated users see global directories only

Files are indexed recursively, with the following rules:

• Hidden files and directories (starting with .) are skipped unless include_hidden: true
• Well-known dependency/cache directories (node_modules, bower_components, jspm_packages, __pycache__, __pypackages__) are skipped unless include_hidden: true
• Binary files are skipped
• Files larger than indexer.max_file_size_mb (default: 1 MB) are skipped
• Files matching sensitive_content_patterns are skipped

Changes to indexed directories are picked up automatically by the file watcher, no server restart is needed. On server start, only files that have been modified since they were last indexed are re-processed. File results appear with the domain local and are served through the Hister web interface directly.

Only when a configured directory is available to the command line client but not to the server, run hister import file with no path arguments. It applies these directory rules locally, extracts matching content, and creates remote file snapshots through the normal add API. The original bytes are not sent. This fallback does not enable tracking. These snapshots are not watched or removed automatically.

When delete_on_remove: true is set on a directory, deleting or renaming a file on the filesystem also removes it from the index automatically. This is opt-in and disabled by default.

No reindex is required when adding or removing files. Files are detected and indexed automatically. After making directory filters more restrictive, run hister cleanup to remove indexed local documents that no longer match the configuration. Cleanup compares indexed paths with the configuration and does not scan or read the filesystem.

Disable Previews

By default, Hister stores the full HTML content of every indexed page on disk and makes it available in a split-pane preview panel in the search and history UI. Setting disable_previews: true turns this off completely:

• HTML content is never written to disk during indexing or re-indexing. Only the extracted plain text, title, URL, domain, language, and favicon are kept.
• Running hister reindex with this option enabled will delete all previously stored HTML files, reclaiming disk space.
• The preview panel, the per-result view button, and the Preview toggle are hidden in the web UI.

This is useful when disk space is limited or when you prefer not to retain full page snapshots.

app:
  disable_previews: true

Note: Favicons are unaffected by this setting and are always stored.

Access Token

The app.access_token setting provides a simple authentication mechanism to secure your Hister instance. When configured, clients must include the token in API requests using the X-Access-Token header or the Authorization: Bearer TOKEN header. This is particularly useful when exposing Hister to the network or internet, preventing unauthorized access to your browsing history and search index.

To use the access token, set it in your configuration file:

app:
  access_token: 'your-secret-token-here'

The web UI prompts for the access token and exchanges it for an opaque browser session. It does not retain the access token in the cookie or in browser storage. The access token has to be added to the browser extension separately when the extension uses token authentication.

Public Mode

Public mode lets anonymous visitors search the shared index while write access remains authenticated. Enable it with app.public: true or by starting the server with hister listen --public. A public instance must also configure either app.access_token or app.user_handling, otherwise Hister refuses to start.

app:
  public: true
  access_token: 'your-secret-token-here'

server:
  base_url: https://hister.example.com

With user handling, anonymous visitors can only see documents stored under user ID 0. User-owned documents remain visible only to the matching authenticated user.

app:
  public: true
  user_handling: true

Public mode exposes search, suggestions, document reads, previews, file serving, API documentation, and MCP search. It does not allow anonymous users to add, edit, label, delete, change rules, reindex, clean up, access web history, or access profile APIs. Authenticated callers can access web history normally.

Only index content that is meant to be public. Local files, previews, and MCP search can expose indexed document content to anonymous visitors.

For command-line usage with curl or similar tools, include the header in your requests:

curl -H "X-Access-Token: your-secret-token-here" http://localhost:4433/api/config

Security note: API clients transmit the access token in plain text with each request, and the web UI transmits it during login. When exposing Hister over the network, always use HTTPS through a reverse proxy to encrypt credentials and sessions in transit. The token provides basic access control but does not replace proper authentication systems for multiple user scenarios.

OAuth

When user handling is enabled, Hister supports delegating authentication to external OAuth 2.0 / OpenID Connect providers. Users can then sign in with their existing accounts instead of a Hister-local password.

The server.oauth key is a map where each key is a provider name and the value is its configuration. Three providers are built in:

Provider	Description
github	GitHub accounts via the GitHub OAuth app
google	Google accounts via Google Identity
oidc	Any OpenID Connect provider (Keycloak, Authentik, Dex, etc.)

Each entry supports the following fields:

GitHub Example

Register an OAuth app at github.com/settings/developers. Set the Authorization callback URL to https://your-hister-instance/api/oauth/callback?provider=github.

server:
  oauth:
    github:
      client_id: 'your-github-client-id'
      client_secret: 'your-github-client-secret'

Google Example

Create OAuth credentials in the Google Cloud Console. Add https://your-hister-instance/api/oauth/callback?provider=google as an authorised redirect URI.

server:
  oauth:
    google:
      client_id: 'your-google-client-id'
      client_secret: 'your-google-client-secret'

Generic OIDC Example

server:
  oauth:
    oidc:
      client_id: 'hister'
      client_secret: 'your-client-secret'
      configuration_url: 'https://accounts.example.com/.well-known/openid-configuration'

If your provider does not publish a discovery document, set auth_url, token_url, and userinfo_url directly and omit configuration_url:

server:
  oauth:
    oidc:
      client_id: 'hister'
      client_secret: 'your-client-secret'
      auth_url: 'https://accounts.example.com/oauth/authorize'
      token_url: 'https://accounts.example.com/oauth/token'
      userinfo_url: 'https://accounts.example.com/oauth/userinfo'

How It Works

1. The login page shows a Sign in with <Provider> button for each configured provider.
2. Clicking the button redirects the user to the provider’s authorization page.
3. After the user grants access the provider redirects back to /api/oauth/callback?provider=<name>.
4. Hister verifies the state token, exchanges the authorization code for a token, and fetches the user’s identity from the provider.
5. If no local account is linked to that identity, one is created automatically. GitHub uses the login name, Google uses the account name with the full email address as a fallback, and OIDC uses preferred_username with the full email address as a fallback.
6. The user is logged in and redirected to the home page.

Note: OAuth login requires app.user_handling: true. The buttons only appear on the login page when user handling is active and at least one provider is configured.

OAuth-Only Mode

Setting server.oauth_only: true prevents users from authenticating with a username/password. Only OAuth logins are accepted through the web interface.

server:
  oauth_only: true
  oauth:
    github:
      client_id: 'your-github-client-id'
      client_secret: 'your-github-client-secret'

Personal access tokens continue to work regardless of this setting, so API clients, the CLI, and the browser extension can authenticate without a browser login. In multiple user mode, app.access_token is a client default and must contain a user’s personal token to authenticate.

The login page hides the username/password form when oauth_only is active, showing only the OAuth provider buttons.

Note: Use oauth_only with app.user_handling: true and at least one configured OAuth provider. Enabling it without a provider leaves users with no browser login path.

Language Detection

The indexer.detect_languages option (default: true) controls automatic language detection for indexed pages. When enabled, Hister uses language detection libraries to identify the language of each page’s content, creating separate language-specific indexes that improve search accuracy through language-aware tokenization and stemming.

The indexer.keep_stopwords option defaults to false. When enabled together with language detection, Hister retains stop words while continuing to apply the other language analyzer operations, including normalization and stemming. This is useful when quoted phrases must include common words such as for and your.

Performance considerations: Language detection increases both CPU usage and memory consumption. Each document requires additional processing to analyze text and determine its language, and separate indexes are maintained for each detected language. If you’re experiencing memory pressure or slow indexing performance, especially with large numbers of documents, consider disabling this feature.

Important: Changing either analyzer setting requires a full reindex to take effect. After changing detect_languages or keep_stopwords, run:

hister reindex

The reindex operation will rebuild all indexes according to the new settings. Hister stores an analyzer configuration fingerprint and warns at startup when the configured settings differ from those used by the current index. With language detection disabled, all documents are indexed using a single default analyzer, reducing memory overhead and simplifying the indexing process at the cost of potentially less accurate search results.

hotkeys.web Section

Defines keyboard shortcuts for the web interface. Each entry maps a key combination to an action.

Key format: [modifier+]key where modifier is ctrl, alt, or meta. Key can be a letter, digit, or special key (enter, tab, arrowup, arrowdown, etc.).

Action	Description
focus_search_input	Move focus to the search input box
open_result	Open the selected (or first) result
open_result_in_new_tab	Open the selected result in a new tab
select_next_result	Move selection to the next result
select_previous_result	Move selection to the previous result
open_query_in_search_engine	Open the current query in the configured fallback search engine
view_result_popup	Open the offline preview popup for the selected result
delete_result	Delete the selected result
autocomplete	Accept the autocomplete suggestion
show_hotkeys	Show the keyboard shortcuts help overlay

TUI Configuration

TUI-specific settings are stored in a separate tui.yaml file in the same directory as your main config. This file is automatically created with defaults the first time you run hister search.

Default location: ~/.config/hister/tui.yaml (or alongside your config file)

tui.yaml Example

dark_theme: 'tokyonight'
light_theme: 'catppuccin-latte'
color_scheme: 'terminal'

hotkeys:
  ctrl+c: 'quit'
  f1: 'toggle_help'
  tab: 'toggle_focus'
  esc: 'toggle_focus'
  up: 'scroll_up'
  k: 'scroll_up'
  down: 'scroll_down'
  j: 'scroll_down'
  enter: 'open_result'
  y: 'copy_result'
  v: 'toggle_preview'
  l: 'edit_label'
  ctrl+d: 'delete_result'
  ctrl+t: 'toggle_theme'
  ctrl+s: 'toggle_settings'
  ctrl+o: 'toggle_sort'
  ctrl+e: 'toggle_semantic'
  alt+1: 'tab_search'
  alt+2: 'tab_history'
  alt+3: 'tab_rules'
  alt+4: 'tab_add'

The default terminal mode does not paint a terminal-wide foreground or background. Normal text inherits your terminal colors, while semantic accents use its configurable ANSI palette. Set color_scheme to auto, dark, or light to opt into Hister’s full built-in themes. The Settings overlay (ctrl+s) exposes this as Appearance — Terminal (pass-through); press Enter to cycle modes, or use ctrl+t for the full theme picker.

TUI Hotkeys

TUI keyboard shortcuts are configured in tui.yaml under the hotkeys section. See the tui.yaml example above.

Action	Description
quit	Exit the TUI
toggle_help	Show/hide the keybindings help overlay
toggle_focus	Change focus or return to the previous workspace
scroll_up	Move selection up
scroll_down	Move selection down
open_result	Open, edit, or submit the focused item
copy_result	Copy the selected URL
toggle_preview	Show/hide selected result details
edit_label	Edit the selected document label
delete_result	Delete the selected entry from the index
toggle_theme	Open the interactive theme picker overlay
toggle_settings	Open appearance and keybinding settings
toggle_sort	Toggle domain-based sorting for search results
toggle_semantic	Toggle semantic search when enabled
tab_search	Switch to the Search tab
tab_history	Switch to the History tab (view recent searches)
tab_rules	Switch to the Rules tab (manage skip/priority/versioning rules and aliases)
tab_add	Switch to the Add tab (manually add URLs and multiline text)

crawler Section

The crawler section configures the web crawler used by hister index, hister index --recursive, browser imports, and service imports that need to download bookmark content. These commands share the same backend and request settings. Every recursive crawl runs as a persistent job so it can be interrupted and resumed without losing progress. See Website Crawler for usage details.

Set proxy to an http:// or socks5:// URL. The HTTP backend uses it as its transport proxy, Chromedp passes it to the browser process, and BiDi requests it when creating the browser session. robots.txt requests use the same proxy. For example:

crawler:
  proxy: 'socks5://127.0.0.1:1080'

Proxy URLs with embedded credentials are rejected because browser backends cannot apply them consistently. You can also set the proxy with HISTER__CRAWLER__PROXY or the --proxy flag.

For BiDi, a configured proxy requires the remote browser to accept session.new with the proxy capability. Initialization fails if the endpoint already owns a session or rejects that capability, so Hister never continues while silently ignoring the proxy.

Crawler Backend Options

The backend_options map passes configuration to the selected backend. Each backend validates its own options and rejects unknown keys.

http backend — no backend-specific options supported.

chromedp backend:

crawler:
  backend: 'chromedp'
  backend_options:
    exec_path: '/usr/bin/chromium'
    capture_delay: 1.5
  timeout: 15

bidi backend (WebDriver BiDi):

Connects to an already-running browser that exposes a WebDriver BiDi WebSocket endpoint. This is the W3C-standard automation protocol supported by Firefox (≥ 102), Chrome (≥ 106), Edge, and other modern browsers. Unlike chromedp, the bidi backend does not launch a browser process — it reuses one you have started yourself (headless or not).

Start your browser with BiDi enabled, for example:

# Firefox
firefox --remote-debugging-port 9222

# Chrome / Chromium
chromium --remote-debugging-port=9222

Then configure Hister to use it:

crawler:
  backend: 'bidi'
  backend_options:
    host: '127.0.0.1'
    port: '9222'
    capture_delay: 1.5 # wait 1.5s after load for JS to render
  timeout: 15

Or using a full socket URL:

crawler:
  backend: 'bidi'
  backend_options:
    socket: 'ws://127.0.0.1:9222/session'

Crawler Cookies

Each entry in cookies is an object with the following keys:

Full Crawler Example

crawler:
  backend: 'http'
  proxy: 'http://127.0.0.1:8080'
  timeout: 10
  delay: 2
  user_agent: 'Hister'
  headers:
    Accept-Language: 'en-US,en;q=0.9'
  cookies:
    - name: 'session'
      value: 'abc123'
      domain: 'example.com'
      path: '/'

sensitive_content_patterns Section

A map of named Go regular expression patterns. Hister rejects a web page or local file when its HTML or extracted text matches any pattern. The content is not redacted or indexed. Indexing commands that support --allow-sensitive can explicitly bypass this check.

sensitive_content_patterns:
  my_pattern: 'regex here'

Default patterns cover common secrets: AWS keys, GitHub tokens, SSH/PGP private keys.

Environment Variables

You can override configuration values using environment variables. The naming convention is:

HISTER__<SECTION>__<KEY>=value

For example:

• HISTER__APP__LOG_LEVEL=debug overrides app.log_level
• HISTER__APP__LOG_FORMAT=json overrides app.log_format
• HISTER__APP__LOG_FILE=/var/log/hister.log overrides app.log_file
• HISTER__SERVER__ADDRESS=0.0.0.0:8080 overrides server.address

Three special purpose variables are also supported:

Variable	Description
HISTER_CONFIG	Select a config file when --config is not supplied
HISTER_PORT	Override the port only while keeping the existing host from server.address
HISTER_DATA_DIR	Override app.directory