# OmniRoute TLS Stealth and Proxy Avoidance: How It Spoofs Browser Fingerprints and Bypasses Proxies

> Discover OmniRoute TLS stealth and proxy avoidance. Spoof browser fingerprints and bypass proxies to evade bot detection. Learn how OmniRoute enhances your network security.

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

---

**OmniRoute TLS stealth and proxy avoidance are dual security capabilities that spoof Chrome‑like TLS fingerprints to evade bot detection and optionally bypass configured egress proxies when direct connections are required.**

The OmniRoute routing engine implements these features through opt‑in configuration flags, allowing operators to masquerade automated traffic as legitimate browser sessions while maintaining fallback pathways for proxy failures.

## What Is TLS‑Fingerprint Stealth in OmniRoute?

The **TLS‑fingerprint stealth** capability hides the fact that traffic originates from a Node.js program rather than a real browser by substituting the default TLS client with one that emits a genuine Chrome handshake.

### How the Spoofing Works

When `ENABLE_TLS_FINGERPRINT` is activated, the **Open‑SSE executors** (`open-sse/executors/`) instantiate HTTP/HTTPS clients via the **wreq‑js** library instead of Node.js native `tls`. This library reproduces the exact **JA3/JA4 hash** of Chrome 124, defeating fingerprint‑based bot detection used by Cloudflare, Akamai, and similar services.

| Configuration Element | Location | Default |
|-----------------------|----------|---------|
| Feature flag definition | [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) | `false` |
| Runtime toggle | Database or env `ENABLE_TLS_FINGERPRINT` | `false` |
| Timeout control | `TLS_CLIENT_TIMEOUT_MS` in [`ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/ENVIRONMENT.md) | Mirrors `FETCH_TIMEOUT_MS` |

The stealth client respects the same timeout semantics as standard fetches, ensuring performance parity while evading detection.

### Why TLS Stealth Matters

- **JA3/JA4 blocking** — Services refuse generic Node.js TLS profiles.
- **Credential binding** — Some providers invalidate sessions when the TLS fingerprint changes mid‑session.
- **Bot detection** — Hosted automation is flagged via TLS signature analysis.

## Proxy Avoidance: Direct‑Egress Fallbacks

OmniRoute normally routes outbound traffic through a **control‑plane proxy** for auditing and egress‑IP control. Two mechanisms allow **proxy avoidance** when the proxy is unreachable or when direct connections are mandated:

### Mechanism 1: Health‑Check Fallback

The `OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK` flag enables automatic direct connections when proxy health checks fail.

```bash

# Enable fallback on proxy failure

OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK=true npm run start

```

This prevents total outage when the control‑plane proxy becomes unavailable.

### Mechanism 2: Host‑Specific Bypass via `NO_PROXY`

The `NO_PROXY` environment variable accepts comma‑separated host patterns that skip proxy resolution entirely through the `resolveProxyForRequest` logic:

```bash

# Bypass proxy for OpenAI API calls

NO_PROXY=api.openai.com npm run start

```

Both mechanisms are **fail‑closed by default**. The proxy is never bypassed without explicit operator configuration, preventing accidental IP leakage.

## Stealth Browser Pool for Web‑Cookie Providers

For providers requiring genuine browser sessions (Cloudflare‑protected flows), OmniRoute runs a **shared stealth browser pool**:

| Component | Implementation | Location |
|-----------|---------------|----------|
| Stealth launcher | `puppeteer-extra-plugin-stealth` | [`open-sse/services/browserPool.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/browserPool.ts) |
| Pool management | Context reuse and cookie extraction | [`open-sse/services/browserPool.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/browserPool.ts) |
| Status tooling | MCP tool `browser_pool_status` | [`open-sse/mcp-server/tools/poolTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/poolTools.ts) |

The pool launches headless Chromium in stealth mode, solves challenges (CAPTCHAs, Cloudflare interstitials), and extracts fresh cookies for downstream requests. The `stealthAvailable` flag indicates whether the stealth launcher is operational.

### Accessing the Browser Pool

```ts
import { getBrowserPool } from '@/open-sse/services/browserPool';

async function refreshGrokCookies() {
  const pool = await getBrowserPool();

  // Launches stealth Chromium, solves challenges, returns fresh cookies
  await pool.refreshCookiesViaBrowser('grok-web');
}

```

Check pool status via MCP:

```bash
omniroute mcp tool browser_pool_status

```

## Enabling TLS Stealth and Proxy Avoidance

### Complete Environment Configuration

```bash

# .env file — TLS fingerprint spoofing

ENABLE_TLS_FINGERPRINT=true
TLS_CLIENT_TIMEOUT_MS=60000

# Proxy fallback configuration

OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK=true
NO_PROXY=api.openai.com,auth.openai.com

npm run start

```

### Runtime Feature Flag Toggle

The `ENABLE_TLS_FINGERPRINT` flag can be modified at runtime through the feature‑flag API by setting the database entry `ENABLE_TLS_FINGERPRINT = true`, enabling dynamic response to changing detection environments.

## Key Source Files

- **`open-sse/executors/`** — HTTP client instantiation with wreq-js substitution when stealth is enabled
- **[`open-sse/services/browserPool.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/browserPool.ts)** — Shared stealth Chromium pool with `stealthAvailable` flag
- **[`open-sse/mcp-server/tools/poolTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/poolTools.ts)** — MCP tooling for pool telemetry
- **[`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts)** — Internal definition of `ENABLE_TLS_FINGERPRINT`
- **[`docs/security/STEALTH_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/STEALTH_GUIDE.md)** — Comprehensive TLS and CLI fingerprint documentation
- **[`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md)** — Environment variable specifications
- **[`docs/reference/FEATURE_FLAGS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/FEATURE_FLAGS.md)** — Feature flag reference

## Summary

- **OmniRoute TLS stealth** spoofs Chrome 124 TLS fingerprints via wreq-js to defeat JA3/JA4 bot detection.
- The `ENABLE_TLS_FINGERPRINT` flag gates this capability, defaulting to `false` for fail‑closed security.
- **Proxy avoidance** provides two pathways: automatic fallback on proxy failure and host‑specific `NO_PROXY` bypass.
- The **stealth browser pool** complements TLS spoofing with genuine Chromium sessions for web‑cookie providers.
- All capabilities are opt‑in, preserving operational safety while enabling evasion when required.

## Frequently Asked Questions

### How does OmniRoute TLS stealth differ from a standard HTTPS proxy?

Standard HTTPS proxies forward encrypted traffic without modifying the TLS handshake. OmniRoute TLS stealth **replaces the client hello entirely**, emitting a fingerprint that matches real Chrome rather than Node.js. This occurs at the application layer before any proxy connection is established.

### Can I enable TLS stealth without the stealth browser pool?

Yes. The `ENABLE_TLS_FINGERPRINT` flag operates independently of the browser pool. TLS stealth handles transport‑level fingerprinting for API calls, while the browser pool provides session‑level authenticity for web‑cookie flows. Enable either or both based on provider requirements.

### What happens if wreq-js fails or the stealth browser pool is unavailable?

The executors fall back to standard Node.js TLS clients when wreq-js encounters errors. The browser pool's `stealthAvailable` flag surfaces availability through the `browser_pool_status` MCP tool, and providers requiring cookies will fail gracefully with clear error messages rather than hanging indefinitely.

### Is proxy avoidance safe for production deployments?

Proxy avoidance is safe when configured deliberately. The `OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK` flag prevents outage cascades when proxies fail, while `NO_PROXY` enables precise exceptions for providers that reject proxied connections. Both require explicit opt‑in, maintaining the principle of least privilege.