# How to Configure Wigolo Behind a Corporate Proxy with TLS Inspection

> Configure Wigolo behind a corporate proxy with TLS inspection. Set PROXY_URL, secure credentials, and export CA cert via NODE_EXTRA_CA_CERTS to establish trust.

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

---

**To configure Wigolo behind a corporate proxy with TLS inspection, set the `PROXY_URL` environment variable, store credentials securely in Wigolo's key-chain, and export the corporate CA certificate via `NODE_EXTRA_CA_CERTS` to establish trust.**

Running Wigolo from the KnockOutEZ/wigolo repository inside a locked-down enterprise network requires specific configuration to route traffic through HTTP/HTTPS proxies and accept TLS-inspected connections. This guide explains how to configure Wigolo behind a corporate proxy with TLS inspection using environment variables, secure credential storage, and Node.js TLS settings.

## Set the Proxy URL and Credentials

Wigolo discovers proxy settings through environment variables and supports credential separation for enhanced security.

### Configure the Proxy URL via Environment Variables

Define `PROXY_URL` with the proxy host, port, and optional user credentials. Wigolo also accepts legacy variables `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` for backward compatibility, as normalized in [`src/util/child-env.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/util/child-env.ts).

```bash
export PROXY_URL="http://alice:s3cret@proxy.corp.example:8080"

```

When `PROXY_URL` contains credentials, Wigolo uses them directly to create Playwright-compatible proxy options. If credentials are omitted, the application looks for stored credentials in the key-chain (see [`src/fetch/proxy-credentials.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/proxy-credentials.ts)).

### Store Credentials Separately in the Key-Chain

For security, omit credentials from the URL and store them separately using Wigolo's internal key-chain:

```bash
wigolo config set proxyUrlCred "alice:s3cret"

```

At runtime, Wigolo combines the stored credential with the bare proxy host (e.g., `http://proxy.corp.example:8080/`) to construct the full proxy URL. This parsing and recomposition logic is validated in [`tests/unit/fetch/proxy-credentials.test.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/tests/unit/fetch/proxy-credentials.test.ts) and [`tests/unit/config/proxy-credential-resolve.test.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/tests/unit/config/proxy-credential-resolve.test.ts).

## Handle TLS Inspection and Certificate Validation

TLS-inspecting proxies present corporate-issued certificates that Node.js must trust before Wigolo can establish connections.

### Trust the Corporate CA Certificate

Export the path to your corporate CA certificate to enable Wigolo to validate the proxy's forged certificates:

```bash
export NODE_EXTRA_CA_CERTS="/path/to/corp-ca.pem"

```

This Node.js-wide setting affects the underlying TLS implementation used by Wigolo's HTTP client layer in [`src/fetch/http-client.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/http-client.ts), ensuring certificate validation succeeds against the corporate root.

### Bypass Certificate Validation (Development Only)

If importing the corporate CA is not possible, you can disable strict validation:

```bash
export NODE_TLS_REJECT_UNAUTHORIZED=0

```

**Warning:** This disables TLS verification globally for the Node.js process and is **not recommended** for production environments. Wigolo's fetch layer respects this setting, but using it exposes connections to man-in-the-middle attacks.

## Configure Proxy Routing and Exclusions

Wigolo supports fine-grained control over which traffic routes through the proxy.

Set `PROXY_EXCLUDE` with a comma-separated list of hosts that should bypass the proxy and connect directly. This is essential for internal services that should not route through the corporate proxy:

```bash
export PROXY_EXCLUDE="localhost,127.0.0.1,internal.corp.local"

```

## Programmatic Configuration Examples

For scripts or automated deployments, configure Wigolo programmatically using the persisted-config API:

```ts
// Set proxy and CA certificate programmatically
import { getConfig } from "wigolo/src/persisted-config";

process.env.PROXY_URL = "http://proxy.corp.example:3128";
process.env.NODE_EXTRA_CA_CERTS = "/etc/ssl/certs/corp-ca.pem";

const cfg = getConfig();
console.log("Effective proxy:", cfg.proxyUrl);

```

Store credentials securely using the key-chain API:

```ts
// Store proxy credentials in Wigolo's key-chain
import { store } from "wigolo/src/persisted-config";

await store.set("proxyUrl-cred", "alice:s3cret");

```

## Verify the Configuration

After setting environment variables and credentials, validate the setup using Wigolo's built-in health check:

```bash
wigolo healthcheck

```

This command attempts a simple request through the configured proxy. If the request succeeds, both the proxy routing and TLS trust chain are correctly configured.

## Summary

- **Set `PROXY_URL`** (or legacy `HTTP_PROXY`/`HTTPS_PROXY`) to define the corporate proxy endpoint in [`src/util/child-env.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/util/child-env.ts).
- **Store credentials securely** using `wigolo config set proxyUrlCred` rather than embedding them in URLs, leveraging [`src/fetch/proxy-credentials.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/proxy-credentials.ts).
- **Trust the corporate CA** by exporting `NODE_EXTRA_CA_CERTS` with the path to your corporate certificate.
- **Avoid `NODE_TLS_REJECT_UNAUTHORIZED=0`** in production; always prefer proper CA trust configuration.
- **Use `PROXY_EXCLUDE`** to define hosts that should connect directly without the proxy.
- **Run `wigolo healthcheck`** to verify proxy connectivity and TLS certificate validation.

## Frequently Asked Questions

### What environment variables does Wigolo check for proxy settings?

Wigolo primarily checks `PROXY_URL`, but also supports legacy variables `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` for compatibility. The [`src/util/child-env.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/util/child-env.ts) module normalizes these values for Wigolo's subprocesses and internal HTTP client.

### How does Wigolo handle proxy credentials securely?

Wigolo separates credentials from the proxy URL through its key-chain API. You can store credentials via `wigolo config set proxyUrlCred`, which Wigolo combines with the bare proxy URL at runtime as implemented in [`src/fetch/proxy-credentials.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/proxy-credentials.ts). This prevents sensitive information from appearing in environment variables or process lists.

### Can I run Wigolo without trusting the corporate CA certificate?

Yes, by setting `NODE_TLS_REJECT_UNAUTHORIZED=0`, but this disables all TLS certificate validation for the Node.js process and exposes you to man-in-the-middle attacks. This setting is respected by Wigolo's fetch layer in [`src/fetch/http-client.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/src/fetch/http-client.ts), but should only be used temporarily in development environments.

### How do I test if my proxy configuration is working?

Run the `wigolo healthcheck` command to perform a test request through the configured proxy. This verifies that the proxy URL is correctly parsed, credentials are resolved from the key-chain, and the TLS certificate chain is trusted according to the logic in [`tests/unit/config/proxy-credential-resolve.test.ts`](https://github.com/KnockOutEZ/wigolo/blob/main/tests/unit/config/proxy-credential-resolve.test.ts).