Configuration

wigolo works with zero configuration. Everything below is optional tuning: search backends, LLM providers for synthesis, fetch behavior, cache lifetimes, and daemon policy.

Resolution order

Every setting resolves the same way:

environment variable  >  ~/.wigolo/config.json  >  built-in default

Env vars win per-field, so you can persist a baseline in config.json and override one knob per process. WIGOLO_CONFIG_PATH relocates the config file itself.

The config command

wigolo config              # interactive settings shell (TUI)
wigolo config --plain      # print current settings and exit
wigolo config --plain --json
wigolo config --set searchBackend=hybrid   # headless single-setting update
wigolo config --storage    # storage usage map
wigolo config --cache-stats
wigolo config --export settings.json       # secrets excluded
wigolo config --import settings.json
wigolo config --cleanup cache              # cache|embeddings|models|browser|searxng

wigolo dashboard is an alias of wigolo config. Secrets (LLM keys, proxy credentials) never go into config.json — they live in the OS keychain (see privacy & security).

Paths and data

Search backend

What the backends mean:

• core (default) — direct search-engine adapters queried in parallel, fused with reciprocal-rank fusion, then reranked by the on-device ML reranker. No sidecar process, no keys.
• searxng — the optional/legacy aggregator sidecar only. Higher long-tail recall on some queries, slower cold start; wigolo manages the sidecar process for you.
• hybrid — runs core first and falls back to the aggregator (merging results) only when a quality signal fires; the merged response names the signal in fallback_signal.

The legacy sidecar has its own knobs when you opt in: WIGOLO_SEARXNG_URL (use an external instance; the legacy SEARXNG_URL is still accepted as a fallback), SEARXNG_MODE (native or docker; with docker the container starts on demand whenever a docker-compatible CLI is on PATH, even if Python is installed — the only option on Windows), SEARXNG_PORT (default 8888).

Fetch and browser engine

Reliability framing matters here: these tiers make wigolo read pages the way a real browser does, and it learns per-domain which tier works (inspect with wigolo tune). When a challenge doesn't clear, the failure is labeled honestly instead of returning junk. Crawling stays polite throughout — robots.txt respected by default, per-domain rate limits, and page budgets sized for research, not bulk harvesting.

For fetching pages behind a login with your own browser session: WIGOLO_CDP_URL (attach to a running browser's debug port), WIGOLO_CHROME_PROFILE_PATH (use a profile), WIGOLO_AUTH_STATE_PATH (a saved storage-state file). Then pass use_auth: true on fetch/crawl. wigolo auth discover lists attachable sessions. A storage-state file is loaded into a fresh context for each fetch; a browser attached over CDP is driven through its existing context, which keeps that browser's own cookies.

On-device models

The default ONNX model downloads once (during init/warmup or lazily on first use) and runs in-process. For a remote/self-hosted Cohere-style rerank endpoint:

export WIGOLO_RERANKER=remote
export WIGOLO_RERANK_API_BASE=http://127.0.0.1:8082/v1
export WIGOLO_RERANKER_MODEL=bge-reranker-v2-m3
# WIGOLO_RERANK_API_KEY works over plain HTTP only on loopback; use HTTPS for any other host.

Wigolo sends { "model": "...", "query": "...", "documents": ["..."], "top_n": 2 } to /rerank. The response must contain results with at least top_n entries shaped { "index": 0, "relevance_score": 0.9 } (or score); if the service scores every document, Wigolo keeps the best top_n. Indexes refer to the original document order. This is a Cohere-style contract; OpenAI does not define a universal rerank API. Queries and candidate text are sent to the configured endpoint. Remote mode does not download the ONNX model. warmup and doctor check configuration without contacting the endpoint; the first rerank request verifies service availability. Search falls back to its existing ordering if the endpoint fails.

Remote embeddings

To use a local or self-hosted embedding service, set WIGOLO_EMBEDDING_API_BASE to an OpenAI-compatible base URL. Wigolo sends { "model": "...", "input": ["..."] } to /embeddings. The response must hold one vector per input in data[].embedding.

Each vector must have 384 values. The vector index uses that size. Wigolo rejects a wrong-size vector with a clear error. Remote mode does not download the bundled embedding model.

Wigolo trims input to WIGOLO_EMBEDDING_MAX_TEXT_LENGTH before the send. The default is 8000 characters. Set the server-side limit above that value if the server also truncates. A server that rejects over-length input now receives trimmed text instead.

export WIGOLO_EMBEDDING_API_BASE=http://127.0.0.1:8080/v1
export WIGOLO_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
# WIGOLO_EMBEDDING_API_KEY works over plain HTTP only on loopback; use HTTPS for any other host.

warmup sends one short probe request. Cache writes and find_similar use the remote endpoint from then on.

Changing the endpoint or the model

The vector store tags each row with a model id. That id combines the model name with the endpoint host and path. find_similar scores only rows that carry the active model id.

A change to WIGOLO_EMBEDDING_API_BASE or WIGOLO_EMBEDDING_MODEL therefore hides every row from the old provider. wigolo backfill selects only URLs with no vector row, so it does not repair them. The CLI has no command that re-embeds one URL. Use the MCP fetch tool with force_refresh: true instead. A plain fetch returns from cache before the embed step runs.

The model id does not change when the weights behind the same endpoint and model name change. Rows from the old weights stay in the index. To re-embed them, call the MCP fetch tool with force_refresh: true for each URL. To drop every vector, run wigolo config --cleanup cache. That command also deletes the cached pages.

LLM providers (optional)

Core tools never need an LLM. Configuring one adds answer synthesis (format: "answer" on search), essay-grade research briefs, and a structured-extraction fallback.

Using an OpenAI-compatible provider

Any service that speaks the OpenAI API works through the openai provider: set its base URL, its key, and one of its model names.

export WIGOLO_LLM_PROVIDER=openai
export OPENAI_BASE_URL=https://api.example.com/v1   # the service's OpenAI-compatible endpoint
export OPENAI_API_KEY=sk-...                        # your key for that service
export WIGOLO_LLM_MODEL=model-name                  # one of its model ids

Keyless local ladder

With WIGOLO_LOCAL_LLM=auto and a local model server running, you get synthesis with zero API keys and zero cloud round-trips.

Cache lifetimes

Per-call force_refresh: true skips both and goes to the network. wigolo cache clear and wigolo config --cleanup cache manage the store; see tools → cache.

Serve / daemon

Full endpoint + auth semantics — including the opt-in compat shim — in REST API and self-hosting.

Telemetry

Off by default, and stays off unless you opt in.

Logging

All logs go to stderr — stdout is reserved for MCP protocol traffic and --json tool output, so logs never corrupt either.

← Docs index · Next: Tools