Complete Guide to Wigolo Environment Variables for Configuration and Performance

Wigolo exposes over 30 WIGOLO_* environment variables that control data directories, TLS impersonation tiers, REST API security limits, and SDK behavior, allowing complete runtime customization without touching configuration files.

The open-source KnockOutEZ/wigolo repository provides a comprehensive search and fetch toolkit that reads runtime preferences from environment variables before falling back to disk configuration. These variables—documented across docs/configuration.md, docs/rest-api.md, and docs/privacy-security.md—enable you to tune performance, harden security, and integrate with external LLM providers entirely through your shell or container orchestration layer.

Core Configuration and Data Paths

Wigolo stores state, cache, and plugins under a root directory that defaults to ~/.wigolo. You can remap this hierarchy and override specific sub-paths using the following variables:

• WIGOLO_DATA_DIR — Root directory for the SQLite cache database, downloaded models, API keys, loaded plugins, and shell history. When unset, defaults to ~/.wigolo as defined in docs/configuration.md.

• WIGOLO_CONFIG_PATH — Absolute path to the JSON configuration file. Use this to relocate config.json outside the data directory for separation of concerns.

• WIGOLO_PLUGINS_DIR — Directory from which Wigolo dynamically loads search-engine and content-extractor plugins. If omitted, resolves to $WIGOLO_DATA_DIR/plugins.

Search Backend and Query Performance

Control how Wigolo dispatches searches and ranks results through query-concurrency and reranking variables:

• WIGOLO_SEARCH — Selects the active backend: core (built-in), searxng (self-hosted meta-search), or hybrid (blended results).

• WIGOLO_GITHUB_TOKEN — Optional Personal Access Token for the GitHub code-search engine. Raises rate limits from 10 to 30 requests per minute and enables private organization repository access.

• WIGOLO_RSS_FEEDS — Comma-separated list of RSS feed URLs injected into news-category results.

• WIGOLO_MULTI_QUERY_MAX — Hard limit on the number of query variants accepted in a single array-query request.

• WIGOLO_MULTI_QUERY_CONCURRENCY — Parallelism level for dispatching multi-query variants simultaneously. Increase this value in docs/configuration.md scenarios where upstream engines tolerate higher connection counts.

• WIGOLO_RERANKER — Reranking strategy applied to result sets. Valid values include onnx (local GPU/CPU inference), none (skip reranking), or a custom plugin identifier.

Browser and Fetch Controls

Fine-tune headless browser behavior, TLS impersonation, and network policies using variables defined in docs/configuration.md:

• WIGOLO_BROWSER_TYPES — Comma-delimited list of browser families used for headless fetching (e.g., chromium,firefox). Defaults to chromium.

• WIGOLO_FETCH_ALLOW_PRIVATE — When set to true, permits fetching URLs that resolve to private or loopback addresses (192.168.x.x, 127.0.0.1). Essential for local development but disable in production, as noted in docs/self-hosting.md.

• WIGOLO_TLS_TIER — Controls JA3 fingerprint impersonation: off (standard TLS), auto (impersonate only on anti-bot signals), or on (always impersonate).

• WIGOLO_STEALTH — Browser fingerprint hardening level: off, auto, or on (maximize anti-detection).

• WIGOLO_TLS_BROWSER — Specific browser profile for TLS impersonation (e.g., chrome_142, safari_ios_16).

• WIGOLO_TLS_SUCCESS_THRESHOLD — Number of successful TLS-tier fetches required before a domain is permanently promoted to TLS-first routing.

• WIGOLO_TLS_DOMAINS — Comma-separated list of domains that always attempt the TLS tier first, bypassing the success-threshold heuristic.

• WIGOLO_CHALLENGE_COMPLETION_MS — Milliseconds to wait for Cloudflare-style JavaScript challenges (default 15000).

• WIGOLO_CDP_URL — Connect to an existing Chrome instance via Chrome DevTools Protocol instead of spawning a new process. Useful for authenticated sessions.

• WIGOLO_CHROME_PROFILE_PATH — Path to a persistent Chrome user profile for cookie and session reuse.

• WIGOLO_AUTH_STATE_PATH — Path to a Playwright-style storage-state.json file for authenticated crawling.

REST API Server and Security Limits

When running wigolo serve, variables from docs/rest-api.md govern binding, authentication, and resource throttling:

• WIGOLO_DAEMON_HOST / WIGOLO_DAEMON_PORT — Override the default 127.0.0.1:3333 bind address. Required when exposing the daemon outside the local machine.

• WIGOLO_API_TOKEN — Bearer token required for non-loopback binds. The server returns 401 Unauthorized if this variable is unset and the bind is public.

• WIGOLO_API_TOKEN_FILE — Filesystem path containing the token (e.g., /run/secrets/wigolo_token). Preferred over WIGOLO_API_TOKEN in Docker Secret or Kubernetes Secret workflows.

• WIGOLO_SERVE_ALLOW_UNAUTHENTICATED — Danger flag. When set to 1, disables token validation for non-loopback addresses. Documented in docs/rest-api.md as a last-resort escape hatch.

• WIGOLO_SERVE_ALLOW_LOCAL_TARGETS — When the server binds to a public interface, this variable must be set to 1 to allow remote callers to fetch localhost or 192.168.x.x URLs. Default blocks such requests to prevent SSRF attacks.

• WIGOLO_SERVE_MAX_BODY_BYTES — Maximum HTTP request body size (default 1048576 bytes; raised to 5242880 for /diff and /extract endpoints).

• WIGOLO_SERVE_TIMEOUT_SCALE — Multiplier applied to default deadlines: search (60s), fetch (120s), and crawl (300s). A value of 2.0 doubles all timeouts.

• WIGOLO_SERVE_MAX_CONCURRENCY — Maximum in-flight HTTP requests handled concurrently (default 16).

• WIGOLO_SERVE_REQUEST_TIMEOUT_MS — Hard deadline for entire request lifecycle (default 120000).

• WIGOLO_SERVE_HEADERS_TIMEOUT_MS — Deadline for receiving HTTP headers (default 60000).

• WIGOLO_FIRECRAWL_COMPAT — When set to 1, mounts an experimental Firecrawl-compatible shim at /compat/firecrawl for drop-in API compatibility.

Privacy and Telemetry Controls

Manage LLM integration and telemetry collection via docs/privacy-security.md:

• WIGOLO_TELEMETRY — Enable local NDJSON event logging to $WIGOLO_DATA_DIR/telemetry/. Set to 1 to activate.

• WIGOLO_TELEMETRY_ENDPOINT — Optional HTTPS endpoint for remote telemetry upload (e.g., https://internal-telemetry.mycompany.com/v1/batch).

• WIGOLO_LLM_API_KEY — API key for the configured LLM provider. Read exclusively from environment variables for security; never persisted to config.json.

• WIGOLO_LLM_PROVIDER — Backend selector for LLM features: openai, anthropic, or ollama.

SDK and Client Integration

The TypeScript SDK and MCP clients respect additional variables documented in sdks/typescript/README.md and examples/vercel-ai-sdk-tools/README.md:

• WIGOLO_BASE_URL — Base URL for the REST daemon (defaults to http://127.0.0.1:3333).

• WIGOLO_LOCAL — Force local-only mode. When 1, the SDK spawns an embedded server instead of connecting to a remote daemon.

• WIGOLO_LOCAL_PORT — Port for the embedded server when WIGOLO_LOCAL=1 (default 3333).

• WIGOLO_CLI — Exec-from-env vector specifying the binary path or argv array the SDK should spawn (e.g., wigolo or ["/usr/local/bin/wigolo", "--verbose"]).

• WIGOLO_MCP_COMMAND / WIGOLO_MCP_ARGS — Override the subprocess command and arguments for MCP (Model Context Protocol) integrations.

Installation and Packaging

Custom installation scripts in packaging/verification/sh.md recognize:

• WIGOLO_INSTALL_SOURCE — Source tarball or npm pack URL for offline installation.

• WIGOLO_INSTALL_PREFIX — Directory prefix for binary installation (e.g., /opt/wigolo).

Practical Configuration Examples

Configure Wigolo for production, development, and SDK scenarios using the variables above.

# Production server with authentication and adjusted limits

export WIGOLO_API_TOKEN=$(openssl rand -hex 32)
export WIGOLO_DAEMON_HOST=0.0.0.0
export WIGOLO_SERVE_MAX_CONCURRENCY=64
export WIGOLO_SERVE_TIMEOUT_SCALE=1.5
wigolo serve

# Development mode with private fetch and SearXNG backend

export WIGOLO_SEARCH=searxng
export WIGOLO_FETCH_ALLOW_PRIVATE=true
export WIGOLO_MULTI_QUERY_CONCURRENCY=8
export WIGOLO_TLS_TIER=off
wigolo serve --dev

# Enable telemetry and remote LLM

export WIGOLO_TELEMETRY=1
export WIGOLO_TELEMETRY_ENDPOINT=https://logs.internal/v1/wigolo
export WIGOLO_LLM_PROVIDER=openai
export WIGOLO_LLM_API_KEY=sk-...
wigolo doctor

// TypeScript SDK client configuration
import { WigoloClient } from 'wigolo-sdk';

const client = new WigoloClient({
  baseUrl: process.env.WIGOLO_BASE_URL,   // falls back to http://127.0.0.1:3333
  token: process.env.WIGOLO_API_TOKEN,    // bearer token if server requires it
});

Summary

• Environment variables take precedence over config.json and hardcoded defaults, making them ideal for immutable infrastructure.
• Security-critical variables like WIGOLO_API_TOKEN_FILE and WIGOLO_SERVE_ALLOW_LOCAL_TARGETS are documented in docs/rest-api.md to prevent accidental exposure.
• Performance tuning relies on WIGOLO_MULTI_QUERY_CONCURRENCY, WIGOLO_SERVE_MAX_CONCURRENCY, and WIGOLO_SERVE_TIMEOUT_SCALE.
• Browser customization uses WIGOLO_TLS_TIER, WIGOLO_STEALTH, and WIGOLO_CDP_URL to evade anti-bot measures.
• Privacy controls include WIGOLO_TELEMETRY and WIGOLO_LLM_API_KEY, the latter reading exclusively from the environment.

Frequently Asked Questions

How do I secure the Wigolo REST API when exposing it publicly?

Set WIGOLO_API_TOKEN to a high-entropy string or use WIGOLO_API_TOKEN_FILE to mount a secret from your orchestrator. Ensure WIGOLO_SERVE_ALLOW_UNAUTHENTICATED is unset or 0. According to docs/rest-api.md, the server fails closed (returns 401) when binding to non-loopback addresses without a token.

What is the difference between WIGOLO_TLS_TIER and WIGOLO_STEALTH?

WIGOLO_TLS_TIER controls transport-layer impersonation (JA3 fingerprints and TLS extensions), while WIGOLO_STEALTH applies high-level browser fingerprint hardening such as viewport randomization and plugin masking. Use both set to on when facing sophisticated bot detection, as documented in docs/configuration.md.

Can I change the data directory without editing the configuration file?

Yes. Export WIGOLO_DATA_DIR to any accessible path. This variable overrides the default ~/.wigolo location for the cache database, plugins, and shell history without requiring changes to WIGOLO_CONFIG_PATH or the JSON config itself.

How do I enable telemetry collection in Wigolo?

Set WIGOLO_TELEMETRY=1 to write NDJSON events locally to $WIGOLO_DATA_DIR/telemetry/. To stream events to a remote collector, additionally define WIGOLO_TELEMETRY_ENDPOINT with your HTTPS ingest URL. These settings are detailed in docs/privacy-security.md.

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