Skip to main content

Configuration Reference

Use Settings in the web interface to configure Nogon, or manage selected settings in a YAML file. A main configuration file is optional. Nogon selects a primary config path using this precedence:

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

An explicit path from --config or an environment variable must exist. An empty NOGON_CONFIG is an error. Without an explicit selection, Nogon searches ./config.yml, then the platform paths below, and uses the first file it finds.

Default Config Locations

Nogon locations are searched first, in the order shown:

PlatformLocations
Linux$XDG_CONFIG_HOME/nogon/config.yml, or ~/.config/nogon/config.yml when XDG_CONFIG_HOME is unset.
macOS$XDG_CONFIG_HOME/nogon/config.yml, or ~/Library/Preferences/nogon/config.yml when XDG_CONFIG_HOME is unset; then ~/Library/Application Support/nogon/config.yml and ~/.config/nogon/config.yml.
Windows%LOCALAPPDATA%\nogon\config.yml, $XDG_CONFIG_HOME\nogon\config.yml, %APPDATA%\nogon\config.yml, then ~\.config\nogon\config.yml. Unset environment locations are skipped.

If none exists, existing Hister locations remain supported. Linux checks the corresponding hister/config.yml, then ~/.histerrc. macOS and Windows check the corresponding Hister platform locations, then ~/.histerrc, then ~/.config/hister/config.yml. Only one main file is loaded; files are never merged. A selected file with invalid contents produces an error instead of falling back.

Data Directory Compatibility

An explicit app.directory or data directory environment variable keeps its selected location. An empty or null app.directory or an inaccessible directory is an error. Existing directories are never copied, moved, or merged automatically.

Without an explicit selection, existing data is reused from supported Nogon or Hister locations. If more than one directory contains stored application data, set app.directory or NOGON_DATA_DIR to choose the intended instance. A main config file or TUI preferences alone do not count as stored application data.

Fresh installations use these defaults:

PlatformData directory
Linux$XDG_STATE_HOME/nogon, then $XDG_DATA_HOME/nogon, then $XDG_CONFIG_HOME/nogon or ~/.config/nogon, using the first configured root.
macOS~/Library/Application Support/nogon
Windows%LOCALAPPDATA%\nogon, falling back to %APPDATA%\nogon

Existing Hister data in any of these roots remains discoverable, including ~/.config/hister on Linux. An existing empty Hister directory is also reused when no populated directory is found. Unix service accounts with /var/empty or /nonexistent as their home and no XDG overrides use /var/lib/nogon, with existing /var/lib/hister data reused. Services with an explicit data location continue using it.

Saved rules, web settings, sessions, indexes, and queued work stay in the selected data directory. Reload keeps the original main file selection and rejects new data directory conflicts until an explicit choice is made.

Setting Precedence

For each setting, the highest priority source wins:

  1. Explicit startup flags.
  2. Environment variables, including NOGON_DATA_DIR and NOGON_PORT and their Hister equivalents.
  3. Explicit values in the main configuration file.
  4. Saved web selections in <app.directory>/config.web.yml.
  5. Built in defaults for the installed version.

Settings shows each value’s source. Main file, environment, and startup flag values are locked, including explicit false, zero, empty values, and values equal to a default. Commented examples do not lock settings. Removing an overriding value exposes any saved web selection underneath it.

The managed file contains only web selections and can contain credentials. Keep it and its backups private. Nogon never rewrites the main file when saving web settings. Changing the data directory selects the managed file in the new directory; it does not move the previous file or its selections. Remote CLI clients use their own local configuration and do not inherit the server’s web selections.

Creating a Config File

Use nogon config path to locate the selected main config, nogon config show to inspect effective YAML with credentials redacted, and nogon config validate to check configuration without creating runtime files. nogon doctor also checks connectivity, authentication, index compatibility, and extractor dependencies. See Terminal Client for examples, output formats, and exit statuses.

Generate a commented reference containing all default settings:

nogon config create ~/.config/nogon/config.yml

Every YAML line is commented, including the listen address for your installed build. Comments do not set values. To activate a setting, remove its leading # and do the same for its enclosing section, preserving indentation. Leave unrelated settings commented. For example:

app:
  title: My Nogon
#   subtitle: Your own search engine

The examples reflect your installed version. Defaults can change after an upgrade. Existing active configuration files keep their meaning. To hand an editable setting to the web editor, comment out or remove that key and reload Nogon. A stored web selection then takes effect, or the default if no web selection exists. Environment variables and startup flags still take precedence.

Use --full to write all defaults as active YAML values:

nogon config create --full /path/to/config.yml

These active values lock their settings in the editor, even when they match the defaults. Nogon does not automatically remove or comment out existing active values.

Omit the filename to print YAML to standard output. New files have private permissions, and existing files are never overwritten. Config creation works even when the current configuration is missing or invalid, and does not initialize runtime data.

Or use your platform’s recommended location:

# Linux
nogon config create ~/.config/nogon/config.yml

# macOS
nogon config create ~/Library/Preferences/nogon/config.yml

# Windows
nogon config create %LOCALAPPDATA%\nogonconfig.yml

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

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

Settings in the Web Interface

Open Settings from the navigation menu, edit fields in any category, then select Save and apply for the complete draft. Discard changes abandons unsaved edits. Validation errors appear beside fields and keep the draft available to correct.

Web configuration requires administrator access in multi user instances. Token protected instances require signing in; instances without authentication need no login. Public search access does not grant anonymous visitors access to Settings on an authenticated instance.

Saving briefly interrupts service. Changes made to configuration files require a reload. Invalid or unreadable files block saving. If another save or a file change causes a conflict, refresh settings and resolve conflicting fields before saving again. If a save or reload response is lost, read the active values before retrying.

Storage locations, executable controls, proxy trust, and OAuth endpoint and identity mapping settings remain file managed. Rules have their own editor; terminal preferences remain local.

Reset, Collections, and Secrets

Reset removes a web selection and inherits the next applicable value. Clear stores an explicit empty value where allowed. Selecting false or zero is also an explicit choice, not a reset. For example, clearing sensitive content patterns disables those checks; resetting them restores inherited patterns.

Lists and dictionaries, including watched directories, headers, cookies, hotkeys, and patterns, are saved as complete collections. An empty collection replaces the inherited collection. If the main file or environment supplies any member, the whole collection is locked. Ordinary nested fields and individual extractor options remain independent; an empty section alone does not lock its settings.

Stored secrets are hidden. Keep preserves a credential, Replace supplies a new one, and Clear stores an empty credential when valid. Reset instead removes the web selection. Keep existing header and cookie credentials when editing other collection rows. Hidden values are not replacement text. Unsaved replacement secrets stay only in the open page and are lost when leaving or reloading it.

When Changes Take Effect

The search engine URL accepts an HTTP or HTTPS address with {query} once in its path or query, for example https://www.google.com/search?q={query}. An empty value uses the default search engine; resetting removes the web selection and inherits the configured value. This destination is shared with visitors, so never include credentials.

SQL debugging logs database queries, which can include private document and account data. Profiler enables runtime profiles at /debug/pprof, which can also contain private data. Disable these troubleshooting options when finished. Metrics enables monitoring at /metrics. Both profiling and metrics require an administrator or the instance token when authentication is enabled; without authentication anyone can access them. Expose version shares the installed version with all visitors. Larger batch request limits allow greater memory use.

Language detection requires at least two selected languages, or an empty selection to detect all supported languages. Reindex existing documents after changing language or stopword settings. Saving does not reindex them automatically.

Watched directories require an absolute path on the server or a ~/ path. Each directory must exist, be readable by the server, and have no overlap with another watched directory, including through symbolic links. An empty owner makes files global; a named owner must already exist in multi user mode. Saving starts a scan and replaces the active watches. Removing a directory stops watching but keeps indexed documents. Changing an owner does not remove documents indexed for the previous owner. Delete those documents separately if their previous visibility is no longer appropriate.

Delete from index when removed removes indexed documents when watched files are deleted or renamed. It never deletes files from disk. An authoritative directory or language list locks the whole collection. PDF parser controls remain managed in the main configuration.

Editing an extractor option does not enable the extractor. Executable paths, arbitrary arguments, and options without supported controls remain file managed. Changes apply to future extraction; fetch documents again to update previously extracted content.

After enabling semantic search or changing its endpoint, model, dimensions, document prefix, context length, or overlap, run nogon reindex to rebuild embeddings for existing documents. Ranking, query, credential, and request limit changes do not need reindexing. Saving does not contact the embedding service to test it or start reindexing. Dimensions must match the model; PostgreSQL supports at most 2000. Chunk overlap must be less than the context length.

An executable path or any other authoritative crawler backend option locks the entire options collection. Executable paths remain managed in the main configuration.

Saved crawler settings apply to subsequent commands using this instance’s configuration and data directory. Running crawls retain their settings. Remote CLI clients use their own local configuration. Saving does not start a crawl or check browser or proxy connectivity. Headers, cookies, and user agent apply to HTTP and Chrome crawls; BiDi uses its browser’s values. Proxy URLs support HTTP and SOCKS5 without credentials.

Stored cookie values cannot be reused with a different name, domain, or path. An authoritative member locks the whole collection. After a revision conflict, use the current values and reapply secret edits. Replacement values remain only in the open page and are discarded after saving or leaving it.

Sensitive content patterns block matching documents during future indexing; existing documents are unchanged. These checks cannot detect every kind of sensitive content.

The pattern collection replaces the inherited patterns, including built in defaults. A pattern supplied by the main configuration or environment locks the whole collection.

Confirming Sensitive Changes

After Save and apply, review the actual changes and consequences before explicitly applying sensitive changes. Cancel keeps the draft without applying it. Editing the draft requires a new review. Enabling SQL debugging or profiling, changing the embedding destination, or removing or replacing sensitive content patterns requires this review but no later access confirmation.

Connection and authentication changes, including the listen address and disabling user handling, apply temporarily. Open Settings at the displayed destination, sign in again if requested, and confirm working access within two minutes to save the complete draft. Changed OAuth settings require a new login through that provider. Credentials are not forwarded to a changed destination. Only one OAuth provider can change at a time; providers that manage administrator roles remain file managed.

Access changes that leave user handling enabled require an existing usable administrator, including an independent local recovery administrator when OIDC manages roles. Settings does not create the first administrator; see User Handling.

Canceling after activation restores the previous configuration. Timeout or restart also restores the last confirmed configuration, including ordinary edits submitted in the same draft. If access fails, wait for rollback and reconnect at the original address with the previous credentials. Other saves and reloads are unavailable while confirmation is pending.

When disabling authentication, keep the originating page open. Its private confirmation code is needed to confirm or restore settings. For a changed destination, copy the code into that Settings page yourself. It cannot be recovered after closing or reloading the originating page. If the code or activation response is lost, wait for rollback. Restoring settings does not undo indexing or other work already performed while the temporary settings were active.

Recovering Saved Settings

If Settings is unavailable or Nogon cannot load its configuration:

  1. Stop Nogon and locate config.web.yml in the instance’s data directory. Use the same main configuration, environment, and startup flags as the service.
  2. Back up the managed file privately before editing it. Correct or remove the affected selection, or move the whole file to a backup location to discard all web selections. A missing managed file is allowed. Malformed, unreadable, or unsupported content must be repaired or removed; a main file override does not bypass these errors.
  3. To override a valid but unwanted web selection, set that value in the main file instead. Environment and startup flags still take precedence. The web selection stays stored and becomes active again if the overriding value is later removed.
  4. Run nogon config validate and inspect nogon config show with the service’s configuration. Check the resulting address and authentication before restarting, especially after removing all web selections. Restart Nogon and reconnect using those settings.

Changing the data directory is not a recovery shortcut: it selects different data and web settings. If Nogon reports failed recovery, preserve the managed file and any recovery copies before restarting and inspect them to choose the intended configuration.

Configuration recovery does not restore passwords, administrator roles, or user accounts. For account recovery, stop the server and use nogon user create --offline --admin USERNAME with the same database and data directory and user handling enabled. Keep the new account’s token if password login is disabled. Do not disable user handling merely to recover an administrator account.

Reloading a Running Server

After editing the main configuration or rules.json, run:

nogon reload

This applies updated settings without manually restarting Nogon. Expect a brief interruption, then refresh any open Nogon web pages. Restart terminal clients separately to apply changes to their own settings.

Edit the configuration file used to start the server. Settings supplied through startup flags or environment variables still take precedence. An admin token is required in multi user mode.

If the server started without a main configuration file, reload still reads its managed web selections, environment, and startup overrides. Restart with --config FILENAME to select a new file. If the server started with a file, that file must remain readable; reload never silently switches to another one.

Logging changes take effect on reload, including app.log_file, app.log_format, and app.log_level. You can also reload after renaming a log file for rotation. Clearing app.log_file sends logs back to the terminal or service logs. If the new log file cannot be opened, Nogon keeps the previous settings.

Invalid settings are rejected. If applying new settings fails, Nogon tries to continue with the previous settings. If it cannot recover, restart the server.

Changing the database or data directory does not copy or move your existing data. Some search setting changes also require nogon reindex; Nogon reports when this is needed.

The command waits for reload to finish. Use --client-timeout N to limit the wait to N seconds. Update the server URL or credentials in your clients if you changed them.

Use the running server’s current URL and token if you have edited connection settings locally:

nogon reload --server-url http://127.0.0.1:4433 --token CURRENT_TOKEN

Environment Variables

You can override configuration values using the Nogon naming convention:

NOGON__<SECTION>__<KEY>=value

For example:

  • NOGON__APP__LOG_LEVEL=debug overrides app.log_level
  • NOGON__APP__LOG_FORMAT=json overrides app.log_format
  • NOGON__APP__LOG_FILE=/var/log/nogon.log overrides app.log_file
  • NOGON__SERVER__ADDRESS=0.0.0.0:8080 overrides server.address

Existing HISTER__* variables still work. If both spellings set the same setting, the Nogon spelling wins, including explicit empty values where supported. The older HISTER_<SECTION>__<KEY> spelling remains supported for keys present in the main file, with lower priority than either double underscore prefix.

Three special purpose variables are also supported:

VariableLegacy spellingDescription
NOGON_CONFIGHISTER_CONFIGSelect a config file when --config is not supplied.
NOGON_PORTHISTER_PORTOverride the TCP port while keeping the host from server.address. Ignored for Unix sockets.
NOGON_DATA_DIRHISTER_DATA_DIROverride app.directory.

For these variables, a present Nogon spelling suppresses its legacy equivalent. Empty NOGON_PORT and NOGON_DATA_DIR values leave the underlying setting in effect. Nonempty values override ordinary environment settings; explicit flags still take precedence. See Data Directory Compatibility for fresh installation defaults and existing data discovery.

Full Configuration

Use the configuration generated by your installed Nogon version instead of copying a static example. Print all current default values as comments:

nogon config create

To write all defaults as active YAML values, add --full and a destination path:

nogon config create --full /path/to/config.yml

Each option below has one or both scope tags. The server tag marks settings used by the Nogon server, its index, or the web interface it serves. The client tag marks settings used by command line operations or the terminal interface on the machine where they run. If your client and server use separate configuration files, add a setting to each tagged side where you need its behavior.

app Section

directory
serverclient

Directory where Nogon stores its data, including the index, rules, and secret key.

Type string
Default platform default
title
server

Main title shown on the web UI home page.

Type string
Default Nogon
subtitle
server

Secondary title shown below the main title on the web UI home page. Set it to an empty string to hide it.

Type string
Default Your own search engine
color_scheme
server

Default web UI color scheme. Supported values are automatic, dark, and light. Visitors can override this default from the appearance menu.

Type string
Default automatic
snippet_length
server

Maximum number of characters in search result text snippets and semantic previews, excluding highlighting and ellipses. Must be positive. Web changes apply immediately; reload or restart after editing the file. No reindexing is needed.

Type int
Default 300
search_url
server

Fallback web search URL. Use {query} as the placeholder for the search term.

Type string
Default https://google.com/search?q={query}
access_token
serverclient

Optional access token for securing the API. See the Access Token section below.

Type string
Default (none)
user_handling
serverclient

Enables multiple user mode. See the User Handling documentation for details.

Type bool
Default false
public
serverclient

Allows unauthenticated users to search public documents, use API docs, MCP search, previews, and file serving. Requires access_token or user_handling.

Type bool
Default false
log_level
serverclient

Log verbosity. Supported values are error, warning, info, debug, and trace. The err and warn aliases are also accepted.

Type string
Default info
log_format
serverclient

Log output format. Text emits colored human readable lines. JSON emits one object per entry for log aggregators.

Type string
Default text
log_file
serverclient

Path to a log file. Nogon creates or appends to this file instead of writing logs to standard error.

Type string
Default (none)
debug_sql
server

Enables verbose SQL query logging.

Type bool
Default false
open_results_on_new_tab
server

Opens search results in a new browser tab instead of the current tab.

Type bool
Default false
show_suggestions
server

Shows the suggestion area in the results view by default. Change Show suggestions in the results page Actions menu to override this setting. Your choice is saved in the current browser.

Type bool
Default false
redirect_on_no_results
server

Redirects to the configured search_url when a query returns no results. Disable it to remain within Nogon.

Type bool
Default true
display_extractor_config
server

Includes extractor option definitions in the extractor API response so clients can display configuration details.

Type bool
Default false
disable_previews
server

Disables the preview panel and prevents HTML storage. See the Disable Previews section below.

Type bool
Default false
profiler
server

Serves the Go runtime profiling endpoints under /debug/pprof, behind the same authentication as the rest of the API.

Type bool
Default false

server Section

address
server

Host and port to listen on, or unix:/absolute/path for a Unix socket. Use [::]:4433 or 0.0.0.0:4433 to listen on all interfaces.

Type string
Default 127.0.0.1:4433
base_url
serverclient

Public URL of the Nogon instance. Required when listening on all interfaces or a Unix socket. It must match how you access Nogon.

Type string
Default derived from address
database
server

SQLite filename relative to app.directory or a PostgreSQL DSN. See Database Backends below.

Type string
Default db.sqlite3
max_batch_body_size
server

Maximum request size in MiB for document uploads, PDF uploads, and batches. For PDFs, the limit includes the encoded content. Import clients use this value to keep submitted batches within the server limit.

Type int
Default 40
metrics
server

Exposes Prometheus metrics at /metrics under the configured base URL. Uses token authentication when configured and requires an administrator in multiple user mode. See Monitoring for setup and metric definitions.

Type bool
Default false
expose_version
server

Includes the running Nogon version in the public /api/config response without authentication. Disabled by default. See Monitoring for setup.

Type bool
Default false
proxy_auth_header
server

Authenticates users by a header set by a trusted authentication proxy and automatically enables user handling. Unsafe without an authentication proxy and protection against direct access. See Reverse Proxy Authentication below.

Type string
Default (empty, disabled)
oauth
server

Optional map of OAuth or OIDC provider configurations. See OAuth below.

Type map
Default (none)
oauth_only
server

Disables password login. OAuth and token based API access remain accepted. In multiple user mode, a token must belong to a user.

Type bool
Default false

For server.metrics and server.expose_version, see Monitoring for setup, access rules, and available information.

For Unix socket permissions and reverse proxy examples, see Unix sockets.

Database Backends

Nogon 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'

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

Nogon 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

enable
server

Enables semantic search. All other semantic search settings are ignored when this is disabled.

Type bool
Default false
embedding_endpoint
server

URL of the OpenAI compatible embeddings endpoint. This URL is visible in settings. Put credentials in api_key or headers, not in the URL.

Type string
Default http://localhost:11434/v1/embeddings
embedding_model
server

Model name passed in each embedding request. It must match a model served by the endpoint.

Type string
Default qwen3-embedding:8b
api_key
server

Optional API key sent as an Authorization bearer token. Hosted providers commonly require it.

Type string
Default ""
headers
server

Optional HTTP headers added to every embedding request for proxies or custom authentication.

Type map[string]string
Default {}
dimensions
server

Requested vector dimensionality. The selected embedding model and endpoint must support this output size. Nogon limits PostgreSQL vector storage to 2000 dimensions.

Type int
Default 2000

Chunking and Input

max_context_length
server

Approximate token budget for each embedding input. Nogon reserves five percent as headroom, giving the default a budget of 486 tokens, and also splits unusually long unbroken text. Models count tokens differently; endpoint rejections trigger another retry with smaller chunks.

Type int
Default 512
chunk_overlap
server

Approximate token allowance shared between consecutive chunks while preserving structural boundaries.

Type int
Default 64
query_prefix
server

Text prepended to every search query. Many embedding models use distinct query and document prefixes for better recall.

Type string
Default "query: "
document_prefix
server

Text prepended to every document chunk. Set it according to the convention expected by the embedding model.

Type string
Default ""

Retrieval

similarity_threshold
server

Minimum cosine similarity required for a semantic chunk to be included in the results.

Type float
Default 0.1
result_limit
server

Maximum number of semantic hits retrieved for each query.

Type int
Default 50
semantic_weight
server

Weight applied to semantic scores when merging them with keyword scores. Zero uses keyword results only, while one uses semantic results only.

Type float
Default 0.4

Processing

embedding_timeout
server

Maximum seconds allowed for one embedding request. Values below one use the default of 300 seconds.

Type int
Default 300
max_embedding_batch_size
server

Maximum chunks sent in one request. Smaller batches keep local endpoints responsive and let long documents make incremental progress. Values below one use the default of eight.

Type int
Default 8
max_embedding_concurrency
server

Maximum embedding workers and simultaneous indexing requests to the endpoint. Query requests have a separate limit. Values below one use the default of two.

Type int
Default 2
max_query_embedding_concurrency
server

Maximum simultaneous query embedding requests, independent of indexing. Values below one use the default of one. Total endpoint concurrency can reach the sum of both limits. Separate slots bypass the local indexing queue but do not reserve capacity or priority on the embedding server.

Type int
Default 1
query_embedding_timeout
server

Maximum seconds allowed for query slot acquisition, the embedding request, and retries combined. On timeout, the search returns its keyword results. This does not bound keyword retrieval or vector lookup. Increase it for slow hardware or model startup. Values below one use the default of two seconds; an earlier caller deadline or embedding_timeout still applies.

Type int
Default 2

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. It supports at most 8192 embedding dimensions and a semantic_search.result_limit of at most 1024.
  • PostgreSQL stores vectors in the same database as the main data using the pgvector extension. Nogon 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 Nogon.

Use NOGON__SEMANTIC_SEARCH__QUERY_EMBEDDING_TIMEOUT and NOGON__SEMANTIC_SEARCH__MAX_QUERY_EMBEDDING_CONCURRENCY to override the query deadline and concurrency through environment variables. Changing these settings does not require reindexing.

Set semantic_search.dimensions to the output size supported by your embedding endpoint. If the endpoint returns a different size, Nogon rejects the embeddings. After changing dimensions with SQLite, restart Nogon and run nogon reindex to rebuild the vector table and regenerate embeddings. Reindexing checks the endpoint before clearing existing vectors and stops if that check fails. Startup logs report when the stored dimensions differ from the configuration.

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
  max_query_embedding_concurrency: 1
  query_embedding_timeout: 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 nogon search.

Theme Settings

dark_theme
client

Theme used in dark mode. Available themes include Catppuccin, Dracula, Gruvbox, Nord, Rose Pine, and Tokyo Night.

Type string
Default tokyonight
light_theme
client

Theme used in light mode.

Type string
Default catppuccin-latte
color_scheme
client

Appearance mode. Terminal inherits your terminal background, foreground, and ANSI palette. Use auto to choose the configured dark or light Nogon theme, or select dark or light explicitly.

Type string
Default terminal
themes_dir
client

Optional directory containing custom theme YAML files.

Type string
Default (built in themes)

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

detect_languages
serverclient

Enables automatic language detection for newly processed documents. Existing documents remain searchable; reindex to apply the setting to them.

Type bool
Default true
languages
serverclient

Limits automatic detection to at least two distinct supported languages. Regional codes and aliases count as the same language. Leave empty to consider all supported languages. A shorter list can reduce memory use, but content in other languages may be misidentified.

Type string[]
Default (none)
language_detection_accuracy
serverclient

Use low (the default) to reduce memory use, or high to improve detection of short text at the cost of more memory. Very short or unclear text can remain unknown in either mode.

Type string
Default low
keep_stopwords
server

Keeps common words such as for and your searchable. Changing this setting requires reindexing.

Type bool
Default false
directories
serverclient

List of local directories to index. See Local Directory Indexing below.

Type Directory[]
Default (none)
max_file_size_mb
serverclient

Maximum file size in megabytes to index. Larger files are skipped.

Type int
Default 1
pdf_parser.command
serverclient

Optional PDF parser executable. Reads PDF bytes from standard input and writes plain UTF 8 text to standard output. See File Types for setup and examples.

Type string
Default (empty, built in reader)
pdf_parser.args
serverclient

Arguments passed literally to the PDF parser command. Requires pdf_parser.command. Each argument is a separate list entry.

Type string[]
Default (none)
pdf_parser.timeout
serverclient

Maximum time in seconds for an external PDF parser command. Must be positive.

Type int
Default 30

See External PDF Parser to use a command such as pdftotext. Environment overrides include NOGON__INDEXER__PDF_PARSER__COMMAND=pdftotext, NOGON__INDEXER__PDF_PARSER__ARGS=-enc,UTF-8,-,-, and NOGON__INDEXER__PDF_PARSER__TIMEOUT=30. Environment arguments are separated by commas; use YAML when an argument contains a comma.

Directory Entry

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

path
serverclient

Directory path to index. Paths beginning with ~/ are expanded to the home directory.

Type string
Default ""
Required
label
serverclient

Label applied automatically to every file indexed from this directory.

Type string
Default ""
filetypes
serverclient

Only indexes files with these extensions, without the dot. For example: ["txt", "md"].

Type string[]
Default (none)
patterns
serverclient

Only indexes filenames matching at least one glob pattern. For example: ["doc_*", "README*"].

Type string[]
Default (none)
excludes
serverclient

Skips filenames matching any listed glob pattern. For example: ["*secret*", "*.tmp"].

Type string[]
Default (none)
include_hidden
serverclient

Includes hidden files, hidden directories, and common dependency or cache directories. Explicit excludes still apply.

Type bool
Default false
delete_on_remove
server

Automatically removes a file from the index when it is deleted or renamed.

Type bool
Default false
user
server

Username that owns files in this directory. Leave it empty for global access.

Type string
Default ""

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 nogon import file for configured directories that the server can access. After editing the configuration file, reload or restart the Nogon server. Changes saved in Settings apply immediately. Nogon scans the directories, then a file watcher monitors them so new and modified files are indexed automatically.

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 with a warning that includes the path but no matched content

nogon list-files lists files matching the configured directory watch rules. It does not check file contents or report indexing status, so it also lists files rejected by sensitive content, size, or format checks. Rejected files remain watched and are checked again when they change.

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 Nogon web interface directly.

When a configured directory is available to the command line client but not to the server, run nogon 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. Add --watch to keep importing new and changed snapshots until interrupted. Watch mode skips exports, archives, and saved HTML with source URL metadata. Remote snapshots are never removed automatically, even with delete_on_remove: true. See Importing Documents for details.

For directories watched by the server, delete_on_remove: true makes deleting or renaming a file on the filesystem remove it from the index automatically. This is optional and disabled by default. It does not apply to remote snapshots imported by the client.

No reindex is required when adding or removing files. Files are detected and indexed automatically. After making directory filters more restrictive, run nogon 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, Nogon 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 nogon reindex with this option enabled will delete all previously stored HTML files, reclaiming disk space.

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 Nogon 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 Nogon 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 nogon listen --public. A public instance must also configure either app.access_token or app.user_handling, otherwise Nogon refuses to start.

Use nogon listen --public=false to override public mode enabled in the file or environment. This explicit choice also remains in effect after reload.

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

Reverse Proxy Authentication

Security warning: Do not enable server.proxy_auth_header without a trusted authentication proxy in front of Nogon. Nogon trusts the configured header as proof of identity and does not verify that the sender is your proxy. Anyone who can supply that header can impersonate an existing user, including an administrator, or create a new account. HTTPS or a reverse proxy that only forwards traffic does not make this safe.

Before enabling this feature, configure your proxy to authenticate requests, discard any client supplied value of the configured header, and set it from the verified user’s identity. Prevent untrusted clients from reaching Nogon directly and bypassing the proxy. Use a loopback listener when the proxy runs on the same host, a Unix socket with restricted permissions, or network rules that restrict backend access to the trusted proxy. Do not expose Nogon’s backend port publicly, including through container port publishing.

Once these protections are in place, set the header name in your Nogon configuration. This example assumes the authentication proxy runs on the same host and sets Remote-User:

server:
  address: 127.0.0.1:4433
  base_url: https://hister.example.com
  proxy_auth_header: 'Remote-User'

The equivalent environment variable is NOGON__SERVER__PROXY_AUTH_HEADER=Remote-User. Use the header name configured in your proxy, such as Remote-User or X-Forwarded-User. Leaving the setting empty disables proxy authentication.

When enabled:

  • Nogon automatically enables app.user_handling.
  • The header value, with surrounding whitespace removed, identifies the Nogon username. An existing account keeps its documents, rules, token, and permissions, including administrator privileges. Use unique identities controlled by the authentication service; users must not be able to choose another Nogon user’s name.
  • A username without an existing account is automatically created on its first request. New accounts have no administrator privileges and no password, so password login is unavailable unless an administrator assigns one.
  • A successfully authenticated proxy identity takes precedence over session cookies and API tokens. Missing or empty headers fall back to normal session and personal access token authentication. Enabling this option does not disable existing password or OAuth login.

CLI, browser extension, and MCP clients can still use a personal access token through X-Access-Token or Authorization: Bearer TOKEN when the proxy header is absent. They must also satisfy your proxy’s access policy. Do not expose the backend to bypass that policy. In multiple user mode, a token must belong to a Nogon user; a standalone app.access_token does not grant access.

Nogon’s Logout action only clears its own session. It does not sign you out of the authentication proxy, so subsequent requests carrying the identity header remain authenticated. Sign out through your authentication proxy to end that access.

See User Handling for account management and document ownership, and Server Setup for listener and reverse proxy configuration.

OAuth

When user handling is enabled, Nogon supports delegating authentication to external OAuth 2.0 / OpenID Connect providers. Users can then sign in with their existing accounts instead of a Nogon-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:

ProviderDescription
githubGitHub accounts via the GitHub OAuth app
googleGoogle accounts via Google Identity
oidcAny OpenID Connect provider (Keycloak, Authentik, Dex, etc.)

Each entry supports the following fields:

client_id
server

OAuth application client ID issued by the provider.

Type string
Required
client_secret
server

OAuth application client secret issued by the provider.

Type string
Required
configuration_url
server

OIDC discovery URL. For OIDC, either set this or configure auth_url, token_url, and userinfo_url directly.

Type string
Conditional
auth_url
server

Overrides the provider authorization endpoint. Required for OIDC when configuration_url is not set. Optional for GitHub and Google.

Type string
Conditional
token_url
server

Overrides the provider token endpoint. Required for OIDC when configuration_url is not set. Optional for GitHub and Google.

Type string
Conditional
userinfo_url
server

Overrides the OIDC user information endpoint. Required when configuration_url is not set or its discovery response does not provide this endpoint.

Type string
Conditional
scopes
server

Additional OAuth scopes to request. Provider defaults are always included.

Type []string
Optional
identity_claim
server

OIDC only. UserInfo claim used to match a Nogon account, such as sub. Empty uses email for compatibility. See OIDC Account Identity before changing this for existing accounts.

Type string
Default email
Optional
admin_groups
server

OIDC only. Membership in any listed group grants administrator access. When configured, each OIDC login also removes administrator access from nonmembers.

Type []string
Default []
Optional
groups_claim
server

OIDC only. Exact UserInfo claim name containing group memberships. Used when admin_groups is configured. Empty uses groups.

Type string
Default groups
Optional
disable_pkce
server

Disables S256 PKCE for this provider. Use only for older providers that reject PKCE parameters.

Type bool
Default false
Optional

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'

GitHub sign in identifies your account by its permanent account ID. A GitHub username change keeps the same Nogon account.

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'

OIDC Account Identity

Set identity_claim: 'sub' to identify an OIDC account by its subject, so changing the user’s email address does not create a new Nogon account. The OIDC specification defines sub as stable and unique within its issuer. Keep the same issuer when using existing account links.

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

The equivalent environment variable is NOGON__SERVER__OAUTH__OIDC__IDENTITY_CLAIM=sub. This works with discovery or manually configured endpoints. The option selects an exact, case sensitive field in the UserInfo response. Custom claim names, including URI names, are supported; dots do not select nested fields. Choose a unique, immutable identifier controlled by the provider. Fields users can edit, such as preferred_username, are unsuitable for account matching.

The selected claim must be a nonempty JSON string containing more than whitespace. If it is missing or invalid, login fails without falling back to email. An email address is optional when another claim identifies the account. New usernames use preferred_username, then email, then the OAuth identity if neither is available. Existing usernames are preserved on subsequent logins.

Omitting identity_claim, leaving it empty, or setting it to email preserves existing oidc-<email> account links. Other claims use oidc:<escaped claim name>:<claim value>, for example oidc:sub:abc123. The claim name uses URL query escaping. This separates identities from different claims and from legacy email identities.

Before switching an existing deployment, back up the database and explicitly relink each affected user’s o_auth_id to the new identity using a verified mapping from the provider. Nogon does not automatically link accounts by matching email addresses or usernames. Without relinking, a successful login with the new claim creates a separate account, and the old account retains its documents and history. Changing the issuer also requires a verified mapping because subjects are unique only within an issuer.

OIDC Administrator Groups

Set admin_groups to manage administrator access through your identity provider:

server:
  oauth:
    oidc:
      client_id: 'hister'
      client_secret: 'your-client-secret'
      configuration_url: 'https://accounts.example.com/.well-known/openid-configuration'
      scopes: ['groups'] # Only if your provider requires this scope.
      admin_groups: ['hister-admins']
      groups_claim: 'groups'

Configure your provider to include group memberships in its UserInfo response as a list of strings. Membership in any configured group grants administrator access. Names match exactly and are case sensitive. Use groups controlled by your identity provider’s administrators. If the claim has another name, set groups_claim to that exact name; dots do not select nested fields. Groups available only in an ID token are not used.

Each successful OIDC login synchronizes the user’s role. Missing, null, or empty groups remove administrator access. Invalid group values prevent login. Manual role changes are replaced at the next OIDC login.

Nogon starts and reloads without a local recovery administrator, but logs a warning. If OIDC login becomes unavailable or all administrator roles are revoked, recovery may require creating an account while the server is stopped. For independent recovery, create a local recovery administrator and keep its personal access token, which works when oauth_only disables password login. Nogon prevents removing or demoting the last usable local recovery administrator. Provider role revocations still take effect.

Group changes take effect at the next OIDC login, then apply to the user’s existing sessions and API token. Nogon does not check group membership between logins. Omitting admin_groups or leaving it empty preserves manually managed roles. Local accounts and other OAuth providers are unaffected.

Environment equivalents are NOGON__SERVER__OAUTH__OIDC__ADMIN_GROUPS=hister-admins,operators and NOGON__SERVER__OAUTH__OIDC__GROUPS_CLAIM=groups.

PKCE and Compatibility

Nogon uses PKCE with the S256 challenge method for GitHub, Google, and OIDC logins by default. Each login generates a fresh private verifier stored in the server side session. The authorization request includes its SHA256 challenge, and the token exchange sends the original verifier. This supports providers such as Kanidm with PKCE enforcement enabled, including when OIDC discovery does not advertise PKCE support.

Existing client IDs, client secrets, scopes, callback URLs, and linked accounts continue to work. Client secrets are still required. No database migration or reindexing is needed, and existing authenticated sessions remain valid.

For an older provider that rejects PKCE parameters, explicitly set disable_pkce: true on that provider:

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

The equivalent environment variable is NOGON__SERVER__OAUTH__OIDC__DISABLE_PKCE=true. Disabling PKCE removes the protection it provides against authorization code interception. Nogon does not automatically retry without PKCE after a provider error.

Logins started before upgrading must be restarted because their sessions lack the verifier and provider binding. A callback consumes its matching login state before exchanging the code, so failed or denied logins must also be restarted. GitHub token exchanges now use a form POST to keep credentials and the verifier out of the URL; custom GitHub token endpoints or proxies must accept POST.

OAuth login requires app.user_handling: true and at least one configured provider. If no local account is linked to the provider identity, Nogon creates one automatically. GitHub uses the login name, Google uses the account name with the full email address as a fallback, and OIDC uses preferred_username, then the full email address, then the OAuth identity as the username.

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.

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.

Search Result Context

Increase app.snippet_length to show more text around keyword matches and longer semantic previews:

app:
  snippet_length: 800

The default is 300 characters. The value must be a positive integer. Highlighting and ellipses do not count toward this limit. Short documents and semantic chunks can return less text. Larger values increase the amount of data returned by each search.

The web app shows up to three lines of each snippet. Select Show more to expand a clipped snippet or Show less to collapse it. To expand snippets by default, enable Always expand snippets in Actions. This preference is remembered in your browser.

You can also set NOGON__APP__SNIPPET_LENGTH=800. Web changes apply immediately; reload or restart after editing the file, and restart after changing the service’s environment. Existing documents use the new length without reindexing.

Language Detection

Nogon identifies document languages locally to help searches match related word forms. The defaults consider all supported languages with reduced memory use:

indexer:
  detect_languages: true
  languages: []
  language_detection_accuracy: 'low'
  keep_stopwords: false

Use languages to limit detection to at least two distinct supported languages, language_detection_accuracy: high to improve detection of short text, or keep_stopwords: true to keep common words searchable. Regional codes and aliases count as the same language.

Setting detect_languages: false turns off automatic detection for newly processed documents. Existing documents remain searchable, and manual language pins are preserved. These settings also apply to service imports run from the command line.

Restart after changing the server configuration. Reindex to apply the new settings to existing documents. Until then, those documents remain searchable with their previous settings.

See Language Settings and Detection for supported codes, configuration examples, accuracy and memory tradeoffs, and instructions for correcting document languages.

hotkeys.web Section

Defines keyboard shortcuts for the search page. Configure key combinations and actions in Settings → Hotkeys. Changes take effect when you return to search. Reload other open search tabs to pick them up. Some combinations are reserved by your browser or operating system.

Built in Tab and arrow key navigation remains available without configured shortcuts. Saving replaces the complete shortcut collection. Any shortcut supplied by the main configuration or environment locks the entire collection. Terminal shortcuts remain in tui.yaml.

Key format: Use lowercase [modifier+]key, with at most one ctrl, alt, or meta modifier. Keys can be letters a to z, digits, /, ?, enter, tab, arrowup, arrowdown, arrowleft, arrowright, or f1 through f12. For example, alt+x can focus the search input.

ActionDescription
focus_search_inputMove focus to the search input box
open_resultOpen the selected (or first) result
open_result_in_new_tabOpen the selected result in a new tab
select_next_resultMove selection to the next result
select_previous_resultMove selection to the previous result
open_query_in_search_engineOpen the current query in the configured fallback search engine
view_result_popupOpen the offline preview popup for the selected result
delete_resultDelete the selected result
autocompleteAccept the autocomplete suggestion
show_hotkeysShow 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 nogon search.

Without a main config file, existing tui.yaml preferences are discovered in the Nogon and legacy Hister config locations. New preferences use the first Nogon config location, such as ~/.config/nogon/tui.yaml on Linux. Saving preferences keeps their selected location.

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

ActionDescription
quitExit the TUI
toggle_helpShow/hide the keybindings help overlay
toggle_focusChange focus or return to the previous workspace
scroll_upMove selection up
scroll_downMove selection down
open_resultOpen, edit, or submit the focused item
copy_resultCopy the selected URL
toggle_previewShow/hide selected result details
edit_labelEdit the selected document label
delete_resultDelete the selected entry from the index
toggle_themeOpen the interactive theme picker overlay
toggle_settingsOpen appearance and keybinding settings
toggle_sortToggle domain-based sorting for search results
toggle_semanticToggle semantic search when enabled
tab_searchSwitch to the Search tab
tab_historySwitch to the History tab (view recent searches)
tab_rulesSwitch to the Rules tab (manage allow/skip/priority/versioning rules and aliases)
tab_addSwitch to the Add tab (manually add URLs and multiline text)

crawler Section

The crawler section configures the web crawler used by nogon index, nogon 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.

backend
client

Scraping backend. Supported values are http, chromedp, and bidi.

Type string
Default http
backend_options
client

Options for the selected backend. See Crawler Backend Options below.

Type map
Default (none)
proxy
client

HTTP or SOCKS5 proxy URL used by every crawler backend.

Type string
Default (none)
timeout
client

Request timeout in seconds.

Type int
Default 5
delay
client

Seconds to wait between requests to avoid overloading target servers.

Type int
Default 0
user_agent
client

Custom User Agent header sent with every request.

Type string
Default (none)
headers
client

Extra HTTP headers sent with every request.

Type map[string]string
Default (none)
cookies
client

Cookies sent with every request. See Crawler Cookies below.

Type Cookie[]
Default (none)
no_robots
client

Disables robots.txt compliance during crawling.

Type bool
Default false

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 NOGON__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 Nogon 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:

Launches Chrome or Chromium on the machine running nogon index. Install the browser there and use exec_path if it is not found automatically. This backend launches its own browser process; Nogon does not currently expose an option to connect it to a remote CDP socket.

exec_path
client

Path to the Chrome or Chromium binary.

Type string
Default (none)
capture_delay
client

Seconds to wait after page load before capturing HTML for pages that rely on JavaScript rendering.

Type float
Default 0
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. Nogon opens the supplied WebSocket and sends session.new; it does not launch a browser or create a session through a WebDriver HTTP server. Firefox supports this direct connection at /session.

Chrome and Chromium’s --remote-debugging-port exposes the Chrome DevTools Protocol (CDP). That socket cannot be used as a BiDi endpoint. Use Nogon’s chromedp backend for a local Chrome or Chromium installation.

See Firefox with BiDi for browser startup and indexing commands, or browser backends with Docker when the server is containerized.

socket
client

Full WebSocket URL. When set, host and port are ignored.

Type string
Default (none)
host
client

Hostname or IP address of the browser WebDriver BiDi endpoint.

Type string
Default 127.0.0.1
port
client

Port of the browser WebDriver BiDi endpoint.

Type string
Default 9222
capture_delay
client

Seconds to wait after page load before capturing HTML for pages that rely on JavaScript rendering.

Type float
Default 0

Apply these settings to the configuration used by the indexing command:

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

The host and port options above produce ws://127.0.0.1:9222/session. Alternatively, specify the full socket URL, including /session. When socket is set, it overrides host and port:

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

The bidi backend subscribes to network.responseCompleted for the tab it navigates, so pages served with a 4xx or 5xx status are reported as fetch failures instead of being indexed as error pages. Redirects are followed and judged by the status of the final response. Statuses of subresources such as images or favicons are ignored. When the browser does not report the subscription, the status stays unknown and the page is indexed as before.

Firefox only allows a single WebDriver session per browser instance. If another client (an IDE integration, a test runner, Selenium, …) already holds the session, Nogon cannot create one and every command fails with invalid session id. Start a dedicated browser instance with its own profile and port for crawling.

Crawler Cookies

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

name
client

Cookie name.

Type string
Required
value
client

Cookie value.

Type string
Required
domain
client

Domain to which the cookie applies, such as example.com.

Type string
Required
path
client

Cookie path.

Type string
Default /
Optional

Full Crawler Example

crawler:
  backend: 'http'
  proxy: 'http://127.0.0.1:8080'
  timeout: 10
  delay: 2
  user_agent: 'Nogon'
  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. Nogon 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.