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:
- The path supplied with
--config. - The path in
NOGON_CONFIG, orHISTER_CONFIGwhenNOGON_CONFIGis unset. ./config.ymlin 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:
| Platform | Locations |
|---|---|
| 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:
| Platform | Data 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:
- Explicit startup flags.
- Environment variables, including
NOGON_DATA_DIRandNOGON_PORTand their Hister equivalents. - Explicit values in the main configuration file.
- Saved web selections in
<app.directory>/config.web.yml. - 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:
- Stop Nogon and locate
config.web.ymlin the instance’s data directory. Use the same main configuration, environment, and startup flags as the service. - 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.
- 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.
- Run
nogon config validateand inspectnogon config showwith 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=debugoverridesapp.log_levelNOGON__APP__LOG_FORMAT=jsonoverridesapp.log_formatNOGON__APP__LOG_FILE=/var/log/nogon.logoverridesapp.log_fileNOGON__SERVER__ADDRESS=0.0.0.0:8080overridesserver.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:
| Variable | Legacy spelling | Description |
|---|---|---|
NOGON_CONFIG | HISTER_CONFIG | Select a config file when --config is not supplied. |
NOGON_PORT | HISTER_PORT | Override the TCP port while keeping the host from server.address. Ignored for Unix sockets. |
NOGON_DATA_DIR | HISTER_DATA_DIR | Override 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
directoryDirectory where Nogon stores its data, including the index, rules, and secret key.
stringplatform defaulttitleMain title shown on the web UI home page.
stringNogonsubtitleSecondary title shown below the main title on the web UI home page. Set it to an empty string to hide it.
stringYour own search enginecolor_schemeDefault web UI color scheme. Supported values are automatic, dark, and light. Visitors can override this default from the appearance menu.
stringautomaticsnippet_lengthMaximum 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.
int300search_urlFallback web search URL. Use {query} as the placeholder for the search term.
stringhttps://google.com/search?q={query}access_tokenOptional access token for securing the API. See the Access Token section below.
string(none)user_handlingEnables multiple user mode. See the User Handling documentation for details.
boolfalsepublicAllows unauthenticated users to search public documents, use API docs, MCP search, previews, and file serving. Requires access_token or user_handling.
boolfalselog_levelLog verbosity. Supported values are error, warning, info, debug, and trace. The err and warn aliases are also accepted.
stringinfolog_formatLog output format. Text emits colored human readable lines. JSON emits one object per entry for log aggregators.
stringtextlog_filePath to a log file. Nogon creates or appends to this file instead of writing logs to standard error.
string(none)debug_sqlEnables verbose SQL query logging.
boolfalseopen_results_on_new_tabOpens search results in a new browser tab instead of the current tab.
boolfalseshow_suggestionsShows 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.
boolfalseredirect_on_no_resultsRedirects to the configured search_url when a query returns no results. Disable it to remain within Nogon.
booltruedisplay_extractor_configIncludes extractor option definitions in the extractor API response so clients can display configuration details.
boolfalsedisable_previewsDisables the preview panel and prevents HTML storage. See the Disable Previews section below.
boolfalseprofilerServes the Go runtime profiling endpoints under /debug/pprof, behind the same authentication as the rest of the API.
boolfalseserver Section
addressHost 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.
string127.0.0.1:4433base_urlPublic URL of the Nogon instance. Required when listening on all interfaces or a Unix socket. It must match how you access Nogon.
stringderived from addressdatabaseSQLite filename relative to app.directory or a PostgreSQL DSN. See Database Backends below.
stringdb.sqlite3max_batch_body_sizeMaximum 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.
int40metricsExposes 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.
boolfalseexpose_versionIncludes the running Nogon version in the public /api/config response without authentication. Disabled by default. See Monitoring for setup.
boolfalseproxy_auth_headerAuthenticates 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.
string(empty, disabled)oauthOptional map of OAuth or OIDC provider configurations. See OAuth below.
map(none)oauth_onlyDisables password login. OAuth and token based API access remain accepted. In multiple user mode, a token must belong to a user.
boolfalseFor 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.
Semantic Search
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
enableEnables semantic search. All other semantic search settings are ignored when this is disabled.
boolfalseembedding_endpointURL of the OpenAI compatible embeddings endpoint. This URL is visible in settings. Put credentials in api_key or headers, not in the URL.
stringhttp://localhost:11434/v1/embeddingsembedding_modelModel name passed in each embedding request. It must match a model served by the endpoint.
stringqwen3-embedding:8bapi_keyOptional API key sent as an Authorization bearer token. Hosted providers commonly require it.
string""headersOptional HTTP headers added to every embedding request for proxies or custom authentication.
map[string]string{}dimensionsRequested vector dimensionality. The selected embedding model and endpoint must support this output size. Nogon limits PostgreSQL vector storage to 2000 dimensions.
int2000Chunking and Input
max_context_lengthApproximate 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.
int512chunk_overlapApproximate token allowance shared between consecutive chunks while preserving structural boundaries.
int64query_prefixText prepended to every search query. Many embedding models use distinct query and document prefixes for better recall.
string"query: "document_prefixText prepended to every document chunk. Set it according to the convention expected by the embedding model.
string""Retrieval
similarity_thresholdMinimum cosine similarity required for a semantic chunk to be included in the results.
float0.1result_limitMaximum number of semantic hits retrieved for each query.
int50semantic_weightWeight applied to semantic scores when merging them with keyword scores. Zero uses keyword results only, while one uses semantic results only.
float0.4Processing
embedding_timeoutMaximum seconds allowed for one embedding request. Values below one use the default of 300 seconds.
int300max_embedding_batch_sizeMaximum 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.
int8max_embedding_concurrencyMaximum embedding workers and simultaneous indexing requests to the endpoint. Query requests have a separate limit. Values below one use the default of two.
int2max_query_embedding_concurrencyMaximum 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.
int1query_embedding_timeoutMaximum 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.
int2Vector Storage Backends
The vector store backend is chosen automatically based on server.database:
- SQLite (default) stores vectors in a separate
vectors.sqlite3file 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 asemantic_search.result_limitof 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
vectortype, which supports at most 2000 dimensions. Make surepgvectoris 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_themeTheme used in dark mode. Available themes include Catppuccin, Dracula, Gruvbox, Nord, Rose Pine, and Tokyo Night.
stringtokyonightlight_themeTheme used in light mode.
stringcatppuccin-lattecolor_schemeAppearance 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.
stringterminalthemes_dirOptional directory containing custom theme YAML files.
string(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_languagesEnables automatic language detection for newly processed documents. Existing documents remain searchable; reindex to apply the setting to them.
booltruelanguagesLimits 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.
string[](none)language_detection_accuracyUse 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.
stringlowkeep_stopwordsKeeps common words such as for and your searchable. Changing this setting requires reindexing.
boolfalsedirectoriesList of local directories to index. See Local Directory Indexing below.
Directory[](none)max_file_size_mbMaximum file size in megabytes to index. Larger files are skipped.
int1pdf_parser.commandOptional 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.
string(empty, built in reader)pdf_parser.argsArguments passed literally to the PDF parser command. Requires pdf_parser.command. Each argument is a separate list entry.
string[](none)pdf_parser.timeoutMaximum time in seconds for an external PDF parser command. Must be positive.
int30See 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:
pathDirectory path to index. Paths beginning with ~/ are expanded to the home directory.
string""labelLabel applied automatically to every file indexed from this directory.
string""filetypesOnly indexes files with these extensions, without the dot. For example: ["txt", "md"].
string[](none)patternsOnly indexes filenames matching at least one glob pattern. For example: ["doc_*", "README*"].
string[](none)excludesSkips filenames matching any listed glob pattern. For example: ["*secret*", "*.tmp"].
string[](none)Includes hidden files, hidden directories, and common dependency or cache directories. Explicit excludes still apply.
boolfalsedelete_on_removeAutomatically removes a file from the index when it is deleted or renamed.
boolfalseuserUsername that owns files in this directory. Leave it empty for global access.
string""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 == usernameplus global directories (userempty 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 unlessinclude_hidden: true - Well-known dependency/cache directories (
node_modules,bower_components,jspm_packages,__pycache__,__pypackages__) are skipped unlessinclude_hidden: true - Binary files are skipped
- Files larger than
indexer.max_file_size_mb(default: 1 MB) are skipped - Files matching
sensitive_content_patternsare 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 reindexwith 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_headerwithout 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:
| 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:
client_idOAuth application client ID issued by the provider.
stringclient_secretOAuth application client secret issued by the provider.
stringconfiguration_urlOIDC discovery URL. For OIDC, either set this or configure auth_url, token_url, and userinfo_url directly.
stringauth_urlOverrides the provider authorization endpoint. Required for OIDC when configuration_url is not set. Optional for GitHub and Google.
stringtoken_urlOverrides the provider token endpoint. Required for OIDC when configuration_url is not set. Optional for GitHub and Google.
stringuserinfo_urlOverrides the OIDC user information endpoint. Required when configuration_url is not set or its discovery response does not provide this endpoint.
stringscopesAdditional OAuth scopes to request. Provider defaults are always included.
[]stringidentity_claimOIDC 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.
stringemailadmin_groupsOIDC only. Membership in any listed group grants administrator access. When configured, each OIDC login also removes administrator access from nonmembers.
[]string[]groups_claimOIDC only. Exact UserInfo claim name containing group memberships. Used when admin_groups is configured. Empty uses groups.
stringgroupsdisable_pkceDisables S256 PKCE for this provider. Use only for older providers that reject PKCE parameters.
boolfalseGitHub 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_onlywithapp.user_handling: trueand 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.
| 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 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.
| 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 allow/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 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.
backendScraping backend. Supported values are http, chromedp, and bidi.
stringhttpbackend_optionsOptions for the selected backend. See Crawler Backend Options below.
map(none)proxyHTTP or SOCKS5 proxy URL used by every crawler backend.
string(none)timeoutRequest timeout in seconds.
int5delaySeconds to wait between requests to avoid overloading target servers.
int0user_agentCustom User Agent header sent with every request.
string(none)headersExtra HTTP headers sent with every request.
map[string]string(none)cookiesCookies sent with every request. See Crawler Cookies below.
Cookie[](none)no_robotsDisables robots.txt compliance during crawling.
boolfalseSet 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_pathPath to the Chrome or Chromium binary.
string(none)capture_delaySeconds to wait after page load before capturing HTML for pages that rely on JavaScript rendering.
float0crawler:
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.
socketFull WebSocket URL. When set, host and port are ignored.
string(none)hostHostname or IP address of the browser WebDriver BiDi endpoint.
string127.0.0.1portPort of the browser WebDriver BiDi endpoint.
string9222capture_delaySeconds to wait after page load before capturing HTML for pages that rely on JavaScript rendering.
float0Apply 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:
nameCookie name.
stringvalueCookie value.
stringdomainDomain to which the cookie applies, such as example.com.
stringpathCookie path.
string/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.