Wigolo Environment Variables: Configuring Search, Caching, and Browser Behavior

Wigolo exposes ten dedicated environment variables that control search result caching policies, cache eviction rules, and headless browser automation settings without requiring code changes.

Wigolo is a flexible search automation framework that reads runtime configuration from environment variables during initialization. By setting specific variables before startup, you can optimize cache retention, select browser engines, and fine-tune network timeouts to match your deployment environment.

Search Caching Configuration

Wigolo maintains an in-memory search cache to avoid redundant requests to external engines. The caching layer is implemented in src/watch/store.ts and respects three primary environment variables that govern entry lifetime and storage limits.

Cache Duration and Size Limits

WIGOLO_SEARCH_CACHE_MAX_AGE defines the maximum age in seconds that a cached search result remains valid. When an entry exceeds this threshold, Wigolo evicts it and issues a fresh request. The default value is 86400 (24 hours).

WIGOLO_SEARCH_CACHE_MAX_SIZE sets the upper bound on the number of cached entries. Once the cache contains this many items, the oldest entry is removed to make room for new results. The default limit is 512 entries.

Disabling Search Caching

WIGOLO_SEARCH_DISABLE_CACHE accepts any non-empty value to completely bypass the cache layer. When this variable is set, every search query hits the remote engine regardless of previous requests. By default, this variable is unset and caching remains enabled.

Search Backend Selection

WIGOLO_SEARCH determines which search backend Wigolo uses for queries. Valid options include core, serpapi, and duckduckgo. The selection affects how search results are fetched and subsequently cached. The default backend is core as defined in src/util/mode.ts.

Browser Behavior Configuration

For rendering JavaScript-heavy pages, Wigolo spawns a headless browser instance controlled by the scheduler in src/watch/scheduler.ts. Six environment variables dictate browser selection, execution mode, and network parameters.

Browser Engine Selection

WIGOLO_BROWSER specifies the browser automation library to use. Supported values are playwright, puppeteer, and chrome. This choice determines the binary and API used for page navigation. The default is playwright.

Headless Mode and Timeouts

WIGOLO_BROWSER_HEADLESS controls whether the browser runs with a visible UI. Set to 1 for headless operation (default) or 0 to launch the browser window for debugging rendering issues.

WIGOLO_BROWSER_TIMEOUT sets the global timeout in milliseconds for browser navigation and script execution. This prevents hangs on slow-loading pages. The default value is 30000 (30 seconds).

Advanced Browser Options

WIGOLO_BROWSER_ARGS accepts a space-separated list of additional CLI arguments passed to the browser process. For example, you can pass --disable-gpu or --disable-web-security to modify browser behavior. By default, no extra arguments are provided.

WIGOLO_BROWSER_PROXY specifies an HTTP proxy URL that the browser uses for all outbound traffic. When unset, the browser connects directly to target sites.

WIGOLO_BROWSER_USER_AGENT overrides the default user-agent string presented to websites. If omitted, Wigolo uses the default user-agent of the selected browser engine.

How Wigolo Reads Environment Variables

During startup, Wigolo sanitizes and validates environment variables through src/util/child-env.ts. This module reads process.env and prepares a clean configuration object passed to the search and browser subsystems. The initialization logic ensures that numeric variables like WIGOLO_SEARCH_CACHE_MAX_AGE are parsed as integers and that boolean flags like WIGOLO_BROWSER_HEADLESS are interpreted correctly. Unit tests in tests/unit/util/child-env.test.ts verify this sanitization behavior across different input formats.

When you modify environment variables, Wigolo applies changes on the next search or browser instantiation. The browser scheduler in src/watch/scheduler.ts recreates the browser instance whenever it detects configuration changes, ensuring that proxy settings or argument updates take effect immediately without requiring a full process restart.

Practical Configuration Example

Export these variables in your shell or .env file before launching Wigolo:

export WIGOLO_SEARCH=core
export WIGOLO_SEARCH_CACHE_MAX_AGE=43200
export WIGOLO_SEARCH_CACHE_MAX_SIZE=256
export WIGOLO_BROWSER=playwright
export WIGOLO_BROWSER_HEADLESS=1
export WIGOLO_BROWSER_TIMEOUT=20000
export WIGOLO_BROWSER_ARGS="--disable-web-security --disable-gpu"
export WIGOLO_BROWSER_PROXY="http://proxy.example.com:8080"

This configuration caches search results for 12 hours, limits the cache to 256 entries, uses Playwright in headless mode with a 20-second timeout, and routes traffic through a corporate proxy.

Summary

• Search caching is controlled by WIGOLO_SEARCH_CACHE_MAX_AGE, WIGOLO_SEARCH_CACHE_MAX_SIZE, and WIGOLO_SEARCH_DISABLE_CACHE, all implemented in src/watch/store.ts.
• Browser automation relies on WIGOLO_BROWSER, WIGOLO_BROWSER_HEADLESS, WIGOLO_BROWSER_TIMEOUT, WIGOLO_BROWSER_ARGS, WIGOLO_BROWSER_PROXY, and WIGOLO_BROWSER_USER_AGENT as defined in src/watch/scheduler.ts.
• Backend selection uses WIGOLO_SEARCH (default core) configured in src/util/mode.ts.
• Environment sanitization occurs in src/util/child-env.ts, ensuring type safety before variables reach the core logic.

Frequently Asked Questions

How do I completely disable search caching in Wigolo?

Set the WIGOLO_SEARCH_DISABLE_CACHE environment variable to any non-empty value, such as 1 or true. When this variable is present, Wigolo skips the cache lookup in src/watch/store.ts and executes a fresh search query for every request.

What is the default browser timeout in Wigolo?

The default browser timeout is 30000 milliseconds (30 seconds), defined by WIGOLO_BROWSER_TIMEOUT. If a page fails to load or execute scripts within this window, the browser instance throws a timeout error and the scheduler may retry depending on your error handling configuration.

Can I use a proxy server with Wigolo's browser automation?

Yes. Set WIGOLO_BROWSER_PROXY to your proxy URL, for example http://user:pass@proxy.example.com:8080. The scheduler in src/watch/scheduler.ts passes this value to the browser instance, forcing all outbound requests through the specified proxy regardless of the selected browser engine.

Where are the environment variables validated?

Wigolo validates and sanitizes all environment variables in src/util/child-env.ts before they reach the search cache or browser scheduler. This module ensures that numeric values are parsed correctly and that default values are applied when variables are omitted, as verified by the test suite in tests/unit/util/child-env.test.ts.

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