# Complete Guide to Wigolo Environment Variables for Configuration and Performance

> Discover over 30 WIGOLO_* environment variables to customize Wigolo's behavior data directories TLS impersonation API security and SDK performance for complete runtime control.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/configuration.md), [`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md), and [`docs/privacy-security.md`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/configuration.md).

- **`WIGOLO_CONFIG_PATH`** — Absolute path to the JSON configuration file. Use this to relocate [`config.json`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/storage-state.json) file for authenticated crawling.

## REST API Server and Security Limits

When running `wigolo serve`, variables from [`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/sdks/typescript/README.md) and [`examples/vercel-ai-sdk-tools/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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.

```bash

# 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

```

```bash

# 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

```

```bash

# 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
// 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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/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`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/privacy-security.md).