Skip to main content

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

The naive binary is the NaïveProxy client. It connects to a frontend server running on your VPS and tunnels your traffic through Chromium’s network stack, making it indistinguishable from ordinary Chrome browser activity. You can configure it with a JSON file or command-line flags, and choose from several local listener protocols depending on your use case.

​
Basic Usage

Download the latest naive binary for your platform from the NaïveProxy releases page. Always use the latest release so the TLS and HTTP signatures remain identical to the current version of Chrome. The simplest way to get started is to create a config.json file in the same directory as the binary: 
{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "https://user:pass@example.com"
}
Then run ./naive — it automatically picks up config.json from the current directory if no arguments are given.
Create config.json in the same directory as the naive binary:
{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "https://user:pass@example.com"
}
Run with the default config file:
./naive
Or point to a specific path:
./naive /path/to/config.json

​
Listen Protocols

The listen field (or --listen flag) controls the protocol and address that naive uses to accept local connections. The URI format is: 
<LISTEN-PROTO>://[<USER>:<PASS>@][<ADDR>][:<PORT>]
LISTEN-PROTO is one of: socks, http, redir. Default values when omitted: protocol socks, address 0.0.0.0, port 1080.

​
SOCKS5

Starts a SOCKS5 proxy server. Most applications and system proxy settings support SOCKS5 natively. 
socks://127.0.0.1:1080
Add optional username and password authentication: 
socks://user:pass@127.0.0.1:1080

​
HTTP Proxy

Starts an HTTP proxy server (supports both CONNECT tunneling and plain HTTP requests). 
http://127.0.0.1:8080

​
Transparent Redirect (redir)

The redir listener is Linux only and requires iptables rules to redirect traffic to it. No authentication is applied.
redir://0.0.0.0:1080
Transparent redirect intercepts TCP connections at the network layer without requiring applications to be proxy-aware. Set up iptables to redirect traffic to the listener port. Redirecting locally originated traffic: 
iptables -t nat -A OUTPUT -d $proxy_server_ip -j RETURN
iptables -t nat -A OUTPUT -p tcp -j REDIRECT --to-ports 1080
Redirecting forwarded traffic on a router: 
iptables -t nat -A PREROUTING -p tcp -j REDIRECT --to-ports 1080
The redir listener also activates a built-in DNS resolver on the same UDP port. Similar iptables rules can redirect DNS queries to this resolver, which returns artificial addresses that are translated back to original domain names in proxy requests and resolved remotely. The artificial DNS results are not saved for privacy. Restarting the resolver may cause downstream clients to cache stale results.

​
Proxy Protocols

The proxy field (or --proxy flag) specifies the upstream server to route traffic through. The full grammar from USAGE.txt is: 
PROXY         = PROXY-CHAIN | SOCKS-PROXY
PROXY-CHAIN   = <PROXY-URI>[,<PROXY-CHAIN>]
PROXY-URI     = <PROXY-PROTO>://[<USER>:<PASS>@]<HOSTNAME>[:<PORT>]
PROXY-PROTO   = http | https | quic
SOCKS-PROXY   = socks://<HOSTNAME>[:<PORT>]
​
https://user:pass@hostname
string
Recommended. HTTP/2 CONNECT over TLS. Provides the strongest camouflage and security, with NaïveProxy’s padding protocol negotiated automatically.
​
quic://user:pass@hostname
string
HTTP/3 CONNECT over QUIC. Use this if https works poorly on your network (e.g., QUIC is less likely to be throttled on some connections). Note: QUIC proxies cannot follow TCP-based proxies in a chain.
​
http://hostname
string
Plain HTTP proxy. No TLS encryption, no NaïveProxy padding. Use only on trusted networks.
​
socks://hostname
string
SOCKS proxy. Does not support chaining, authentication, or NaïveProxy padding.

​
Proxy Chaining

You can route traffic through multiple proxies in sequence by separating proxy URIs with commas: 
{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "https://user:pass@proxy1.com,https://user2:pass2@proxy2.com"
}
Or with flags: 
./naive --listen=socks://127.0.0.1:1080 \
        --proxy=https://user:pass@proxy1.com,https://user2:pass2@proxy2.com
NaïveProxy padding is negotiated with the last proxy in the chain. Keep the following limitations in mind:
  • QUIC cannot follow TCP-based proxies in a chain.
  • No loops — you must ensure the chain does not cycle back to a previous proxy.
  • SOCKS proxies do not support chaining, authentication, or NaïveProxy padding.

​
Multiple Listeners

To listen on more than one local port simultaneously, provide multiple listen values. Each listener is paired with the proxy value at the same position. 
{
  "listen": [
    "socks://127.0.0.1:1080",
    "http://127.0.0.1:8080"
  ],
  "proxy": [
    "https://user:pass@proxy1.com",
    "https://user:pass@proxy2.com"
  ]
}
The number of listen values must match the number of proxy values when both are arrays.

​
Timeout Settings

​
tunnel-timeout
integer
default:"1800 (600 on Android)"
After this many seconds, a tunnel connection is retired: new streams are sent through new connections, and the old tunneled streams are forcibly closed by the idle timeout if idle, or by the tunnel timeout if still active. The retired connection is closed once all its tunneled streams finish.This setting helps with CGNAT networks where long-lived connections get stuck, but it will break long-lived TCP protocols such as SSH.
​
idle-timeout
integer
default:"600 (300 on Android)"
After being idle for this many seconds, tunneled streams are forcibly closed to allow timely cleanup of retired connections. A stream idle long enough is assumed to be unused, so the forced closure has minimal impact.

​
Other Options

​
extra-headers
string
Appends extra headers to requests sent to the proxy server. Separate multiple headers with CRLF (\r\n).
​
host-resolver-rules
string
Statically maps a hostname to an IP address, bypassing DNS for that host. Useful when the proxy hostname itself needs a known IP.
./naive --host-resolver-rules="MAP proxy.example.com 1.2.3.4"
​
resolver-range
string
default:"100.64.0.0/10"
The CIDR range used by the built-in DNS resolver (activated with the redir listener). Artificial addresses are allocated from this range.
​
no-post-quantum
boolean
Disables X25519Kyber768 post-quantum key agreement. Post-quantum key agreement is enabled by default. Pass this flag only if you experience compatibility issues.

​
Logging

By default, naive produces no logs to protect user privacy. Logging can be enabled selectively for debugging.
​
log
string
Save the log to a file at the given path. If the path is empty (--log=), logs are printed to the console instead.
./naive --log=/var/log/naive.log
# or print to console:
./naive --log=
​
log-net-log
string
Save a Chromium NetLog file for detailed network-level inspection. View the captured log at netlog-viewer.appspot.com.
./naive --log-net-log=/tmp/naive-netlog.json
​
ssl-key-log-file
string
Save TLS session keys to a file for decrypting traffic in Wireshark.
./naive --ssl-key-log-file=/tmp/ssl-keys.log

​
Insecure Concurrency

Using --insecure-concurrency with more than a small value undermines NaïveProxy’s core security guarantees. Multiple parallel tunnel connections are more easily detected by traffic analysis. This project is designed for the strongest possible resistance to censorship — using this option in an aggressive way defeats its purpose entirely.
​
insecure-concurrency
integer
default:"1"
Open N concurrent tunnel connections to improve robustness under poor network conditions (e.g., high packet loss). More connections increase detectability.If you must use this option, start with N=2 to see if it resolves your issues. Values above 4 are strongly discouraged.
./naive --insecure-concurrency=2

Build docs developers (and LLMs) love

Get started for freeTalk to us