# Environment Variables That Control OmniRoute's Proxy Behavior and TLS Stealth

> Discover OmniRoute environment variables that control proxy behavior and TLS stealth. Learn how HTTP_PROXY and others manage outbound routing and TLS fingerprinting for enhanced security.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-27

---

**OmniRoute relies on environment variables—including `HTTP_PROXY`, `ENABLE_TLS_FINGERPRINT`, `TLS_CLIENT_TIMEOUT_MS`, and `OMNIROUTE_TLS_CERT`—to govern outbound proxy routing, free proxy family selection, and TLS fingerprint impersonation for stealth operations.**

OmniRoute's networking stack in the `diegosouzapw/OmniRoute` repository is configured almost entirely through environment variables. These variables control everything from global HTTP proxy chains to advanced **TLS fingerprint stealth modes** that mimic real browsers. Understanding these configuration options is essential for deploying OmniRoute securely in both client and server contexts.

## Global Proxy Resolution (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`)

OmniRoute respects standard proxy environment variables to route outbound requests. In [`open-sse/utils/proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyDispatcher.ts) (lines ≈ 20‑30), the dispatcher checks for these variables before initiating any fetch operation.

- **`HTTP_PROXY`** – Routes all HTTP requests through the specified proxy URL.
- **`HTTPS_PROXY`** – Routes all HTTPS requests through the specified proxy URL.
- **`NO_PROXY`** – Comma-separated list of hosts that should bypass the proxy.

If these variables are set, the dispatcher automatically tunnels all outbound traffic through the configured proxy endpoint.

## Free Proxy Family Selection (`FREE_PROXY_*`)

When global proxies are not configured, OmniRoute can automatically select from built-in free proxy families. The logic resides in [`open-sse/utils/proxyFamily.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFamily.ts) (lines ≈ 40‑70), which reads boolean flags to determine which upstream provider to use.

Key variables include:

- **`FREE_PROXY_1PROXY_ENABLED`** – Toggles the 1proxy family.
- **`FREE_PROXY_PROXIFLY_ENABLED`** – Toggles the Proxifly family.
- **`FREE_PROXY_IPLOCATE_ENABLED`** – Toggles the IPlocate family.
- **`FREE_PROXY_WEBSHARE_ENABLED`** – Toggles the Webshare family.
- **`FREE_PROXY_WEBSHARE_API_KEY`** – Provides the API key for Webshare authentication.

The proxy family resolver returns a `ProxyConfig` object that the dispatcher hands to the fetch implementation.

## Fail-Open Behavior and SOCKS5 (`PROXY_FAIL_OPEN`, `ENABLE_SOCKS5_PROXY`)

Two additional flags control resilience and protocol support:

- **`PROXY_FAIL_OPEN`** – When set to `"true"`, this variable changes the default fail-closed behavior. If a proxy connection fails, the resolver returns `null` instead of aborting, allowing the request to proceed without a proxy. This is validated in [`tests/unit/safe-resolve-proxy-fail-closed.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/safe-resolve-proxy-fail-closed.test.ts) (line ≈ 10).

- **`ENABLE_SOCKS5_PROXY`** – Enables the built-in SOCKS5 proxy layer utilized by the proxy-fetch utilities. When active, OmniRoute can route traffic through SOCKS5 proxies in addition to HTTP proxies. See [`tests/unit/socks5-default-on.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/socks5-default-on.test.ts) (line ≈ 14) for implementation details.

## TLS Fingerprint Stealth (`ENABLE_TLS_FINGERPRINT`)

The **TLS stealth mode** is controlled by the `ENABLE_TLS_FINGERPRINT` variable, declared in [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) (line 110). When set to `"true"`, OmniRoute activates the TLS impersonation client.

In [`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts), the code checks this flag to decide whether to wrap the native fetch with the **TLS client** ([`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts)). This client uses a native add-on to reproduce the TLS handshake of a specific browser, helping bypass Cloudflare and other fingerprint-based detection systems.

## TLS Client Timeout (`TLS_CLIENT_TIMEOUT_MS`)

Long TLS handshakes can hang indefinitely without proper timeout configuration. The `TLS_CLIENT_TIMEOUT_MS` variable overrides the default fetch timeout for the TLS impersonation client.

This value is read by [`src/shared/utils/runtimeTimeouts.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/runtimeTimeouts.ts) (line 189) and passed directly to the TLS client constructor. Set this to a high value (e.g., `60000` for 60 seconds) when targeting slow or heavily filtered endpoints.

## Server-Side TLS Termination (`OMNIROUTE_TLS_CERT`, `OMNIROUTE_TLS_KEY`)

When running OmniRoute as a server (`omniroute serve`), you can enable HTTPS by providing TLS certificate files:

- **`OMNIROUTE_TLS_CERT`** – Path to the full certificate chain (e.g., `fullchain.pem`).
- **`OMNIROUTE_TLS_KEY`** – Path to the private key (e.g., `privkey.pem`).

As validated in [`tests/unit/tls-options.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/tls-options.test.ts) (lines ≈ 33‑73), both variables must be present and readable for the server to start in HTTPS mode. If only one is set, OmniRoute falls back to HTTP and emits a warning.

## System Trust Bypass (`OMNIROUTE_SKIP_SYSTEM_TRUST`)

During initialization, OmniRoute can install a generated Certificate Authority (CA) into the host OS trust store. To skip this step—useful in CI environments where modifying system trust stores requires elevated permissions—set:

- **`OMNIROUTE_SKIP_SYSTEM_TRUST`** – Set to `1` or `"true"` to prevent automatic CA installation. This behavior is tested in [`tests/unit/system-trust-test-guard.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/system-trust-test-guard.test.ts) (line ≈ 9).

## Configuration Examples

### Enabling TLS Stealth for Outbound Requests

```bash
export ENABLE_TLS_FINGERPRINT=true
export TLS_CLIENT_TIMEOUT_MS=60000

```

With these settings, all fetches in [`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts) automatically use the TLS impersonation client to mimic browser fingerprints.

### Running OmniRoute as an HTTPS Server

```bash
export OMNIROUTE_TLS_CERT=/path/to/fullchain.pem
export OMNIROUTE_TLS_KEY=/path/to/privkey.pem
omniroute serve --port 8443

```

Omitting either variable results in a plain HTTP server with a console warning.

### Using Webshare Proxy Family

```bash
export FREE_PROXY_WEBSHARE_ENABLED=true
export FREE_PROXY_WEBSHARE_API_KEY=your-api-key-here

```

The [`proxyFamily.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/proxyFamily.ts) resolver will now prioritize Webshare proxies for outbound connections.

### CI Mode Without System Trust Modifications

```bash
export OMNIROUTE_SKIP_SYSTEM_TRUST=1
omniroute start

```

This prevents permission errors in containerized or CI environments where system CA stores are read-only.

## Summary

- **Standard proxy variables** (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) in [`proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/proxyDispatcher.ts) control global routing.
- **Free proxy families** (`FREE_PROXY_*` flags) in [`proxyFamily.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/proxyFamily.ts) enable automatic proxy selection from specific providers.
- **TLS stealth** (`ENABLE_TLS_FINGERPRINT`) activates browser-mimicking TLS handshakes via [`tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tlsClient.ts).
- **TLS timing** (`TLS_CLIENT_TIMEOUT_MS`) prevents handshake hangs by setting custom timeouts in [`runtimeTimeouts.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/runtimeTimeouts.ts).
- **Server TLS** (`OMNIROUTE_TLS_CERT` and `OMNIROUTE_TLS_KEY`) enables HTTPS mode; both must be present or the server falls back to HTTP.
- **Operational flags** (`PROXY_FAIL_OPEN`, `ENABLE_SOCKS5_PROXY`, `OMNIROUTE_SKIP_SYSTEM_TRUST`) fine-tune error handling and CI compatibility.

## Frequently Asked Questions

### What happens if I only set `OMNIROUTE_TLS_CERT` without `OMNIROUTE_TLS_KEY`?

OmniRoute will start in HTTP mode without TLS encryption. According to the validation logic in [`tests/unit/tls-options.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/tls-options.test.ts), both variables must be present and readable to trigger `https.createServer`. If either is missing, the server emits a warning and binds to a plain HTTP socket.

### How does `ENABLE_TLS_FINGERPRINT` bypass Cloudflare detection?

When enabled, OmniRoute routes requests through the native TLS client implemented in [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts). This client replicates the exact TLS handshake parameters—such as cipher suites and extensions—of a real browser, making the request appear to originate from standard consumer software rather than an automated tool or data center server.

### Can I enable multiple `FREE_PROXY_*` families simultaneously?

Yes. The [`proxyFamily.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/proxyFamily.ts) resolver checks all enabled flags and can cycle through multiple families based on availability and priority. However, specific selection logic depends on the implementation details of each family provider in the dispatcher.

### What is the default behavior when a proxy connection fails?

By default, OmniRoute operates in **fail-closed** mode, aborting the request if the proxy is unreachable. Setting `PROXY_FAIL_OPEN=true` changes this to **fail-open** mode, where the dispatcher returns `null` and allows the request to proceed directly without a proxy, as demonstrated in [`tests/unit/safe-resolve-proxy-fail-closed.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/safe-resolve-proxy-fail-closed.test.ts).