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

> Discover Wigolo environment variables to easily configure search caching, eviction rules, and headless browser automation without code changes. Optimize your Wigolo setup now.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: configuration
- Published: 2026-07-19

---

**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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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:

```bash
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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/src/watch/scheduler.ts).
- **Backend selection** uses `WIGOLO_SEARCH` (default `core`) configured in [`src/util/mode.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/util/mode.ts).
- **Environment sanitization** occurs in [`src/util/child-env.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/tests/unit/util/child-env.test.ts).