How to Configure Wigolo Behind a Corporate Proxy with TLS Inspection

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.

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).

Store Credentials Separately in the Key-Chain

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

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 and 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:

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, 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:

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:

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:

// 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:

// 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:

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.
• Store credentials securely using wigolo config set proxyUrlCred rather than embedding them in URLs, leveraging 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 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. 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, 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.

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