TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/klzgrad/naiveproxy/llms.txt
Use this file to discover all available pages before exploring further.
naive binary accepts configuration either as command-line flags or as a JSON config file. Every option documented here corresponds directly to a key in the JSON config file. Flags take precedence over config file values when both are supplied. You can also specify the same flag multiple times on the command line — this is equivalent to providing an array of strings for that key in the JSON file.
Usage Synopsis
Connection Options
Listens for incoming proxy connections at the specified address and port using the given protocol.URI format:Supported protocols (
Defaults: protocol iptables rules for redirecting locally originated traffic:iptables rules for redirecting forwarded traffic on a router:
LISTEN-PROTO):| Value | Description |
|---|---|
socks | SOCKS5 proxy listener |
http | HTTP CONNECT proxy listener |
redir | Transparent redirect listener (Linux iptables) |
socks, address 0.0.0.0, port 1080.This flag can be specified multiple times to listen on multiple ports simultaneously. When multiple listen URIs are given, the number of --proxy values must match, and each listener is paired with the proxy at the same position.The
redir protocol operates without authentication and requires iptables rules to redirect traffic into naive. It also activates a built-in DNS resolver on the same UDP port, which returns artificial addresses that are translated back to original domain names inside proxy requests and then resolved remotely. These artificial results are not saved for privacy — restarting the resolver may cause downstream clients to cache stale results.Routes outgoing traffic through the specified proxy or proxy chain.Grammar:Supported proxy protocols (
Default: direct connection (no proxying).The last
PROXY-PROTO):| Value | Description |
|---|---|
https | HTTP/2 CONNECT proxy over TLS — standard NaïveProxy transport |
quic | HTTP/3 CONNECT proxy over QUIC — alternative NaïveProxy transport |
http | Plain HTTP CONNECT proxy (no TLS) |
socks | SOCKS5 proxy (no chaining, authentication, or Naive padding) |
PROXY-URI in a chain is automatically negotiated for NaïveProxy padding. Multiple proxy URIs can be chained with commas to form a multi-hop route.When multiple --proxy values are provided, they must match the number of --listen URIs exactly, and each listener is routed to the proxy at the same positional index.Limitations:- QUIC proxies cannot follow TCP-based proxies in a chain.
- You must ensure there are no loops in the proxy chain.
- SOCKS proxies do not support chaining, authentication, or NaïveProxy padding.
Concurrency and Timeout Options
Opens
N concurrent tunnel connections for a single proxy session, which can improve robustness on unreliable networks.Default: 1 (single connection).Every additional connection increases the detectability of your traffic. If you are experiencing reliability issues, try N=2 first before increasing further. Using more than 4 connections is strongly discouraged.The maximum lifetime of a single tunnel connection. Once a tunnel connection reaches this age it is retired: new streams are opened on fresh connections, and any streams still running on the retired connection are forcibly closed either by the idle timeout (if idle) or by the tunnel timeout (if still active). The retired connection is finally closed once all its tunneled streams have been closed.This helps with CGNAT environments where long-lived connections get stuck, but will break long-lived TCP protocols such as SSH.Default:
1800 seconds (30 minutes); 600 seconds (10 minutes) on Android.The maximum time a tunneled stream can remain idle. Streams idle beyond this threshold are forcibly closed, enabling timely cleanup of retired connections. When a stream has been silent long enough, it is assumed unused and the forced closure is considered a mild disruption.Default:
600 seconds (10 minutes); 300 seconds (5 minutes) on Android.Request and Resolver Options
Appends one or more extra HTTP headers to every request sent to the proxy server. When supplying multiple headers, separate each header with CRLF (
\r\n).Example:Statically resolves a domain name to a fixed IP address, bypassing DNS. Useful when the proxy server hostname cannot be resolved through normal DNS.Example:
Sets the IP address range used by the built-in DNS resolver (activated when using the
redir listen protocol). The resolver allocates artificial addresses from this range and maps them back to domain names inside proxy requests.Default: 100.64.0.0/10 (IANA Shared Address Space).Logging and Diagnostic Options
Enables logging output. If a file path is provided, the log is written to that file. If the path is empty (
--log=), the log is printed to the console.Default: no log is saved or printed, for privacy.Saves a Chromium NetLog capture to the specified file path. NetLog files record low-level network events and are useful for debugging connection issues.View the captured file at https://netlog-viewer.appspot.com/.
Saves TLS session keys to the specified file in NSS Key Log format. The key log can be loaded into Wireshark to decrypt and inspect TLS traffic for debugging.
Security Options
Disables the X25519Kyber768 post-quantum key agreement algorithm. Post-quantum key exchange is enabled by default to protect against future quantum-computer-based decryption of recorded traffic. Use this flag only if you are experiencing compatibility issues with your proxy server.
General Options
Prints the
naive version string and exits. Always use the latest release — keeping the version current ensures TLS fingerprints remain identical to the current Chrome release.Prints the usage help message and exits.