NaïveProxy JSON Configuration Reference: All Fields

naive can be configured either via command-line flags or a JSON configuration file. The JSON format is the recommended approach for persistent deployments because it keeps all settings in one place and integrates cleanly with process managers. Every JSON field maps directly to its corresponding CLI flag — just strip the -- prefix from any flag name to get the JSON key.

Config File Basics

By default, naive looks for a file named config.json in the current working directory when run with no arguments:

# Uses ./config.json automatically
./naive

# Explicit path
./naive /path/to/config.json

# Or via flag — flags override config file values
./naive --listen=socks://127.0.0.1:1080 --proxy=https://user:pass@example.com

Precedence: Command-line flags always override values set in the config file. You can use a config file as a base and selectively override individual fields at runtime with flags.

Specifying a flag multiple times on the command line is equivalent to setting that key to an array of strings in the JSON file. This is the primary way to configure multiple listeners or multiple proxy routes:

# CLI: two listeners
naive --listen=socks://127.0.0.1:1080 --listen=http://127.0.0.1:8080 --proxy=https://user:pass@example.com

# JSON equivalent
{
  "listen": ["socks://127.0.0.1:1080", "http://127.0.0.1:8080"],
  "proxy": "https://user:pass@example.com"
}

Config File Fields

listen

string | string[]

required

The address(es) and protocol(s) on which naive listens for incoming connections.Format: <LISTEN-PROTO>://[<USER>:<PASS>@][<ADDR>][:<PORT>]Accepted LISTEN-PROTO values: socks, http, redir.
Defaults: protocol socks, address 0.0.0.0, port 1080.Provide a single string for one listener or an array of strings for multiple listeners. When using multiple listeners, the number of proxy entries must match, paired by position.See —listen for full details including redir iptables setup.

"listen": "socks://127.0.0.1:1080"

proxy

string | string[]

The proxy or proxy chain through which outgoing traffic is routed.Format: <PROXY-PROTO>://[<USER>:<PASS>@]<HOSTNAME>[:<PORT>]
Accepted PROXY-PROTO values: https, quic, http, socks.
Multiple hops can be chained with commas in a single string.Default: direct connection (no proxying).When set to an array, the number of entries must match the number of listen entries — each listener is routed to its positionally paired proxy.See —proxy for full grammar, protocol notes, and limitations.

"proxy": "https://user:pass@example.com"

insecure-concurrency

integer

default:"1"

Number of concurrent tunnel connections to open per session. Increasing this value can help with unreliable networks but reduces security by making traffic easier to fingerprint.Try 2 first if you need more than the default. Values above 4 are strongly discouraged.Equivalent CLI flag: --insecure-concurrency

"insecure-concurrency": 2

tunnel-timeout

integer

default:"1800 (600 on Android)"

Lifetime of a tunnel connection in seconds. After this timeout the connection is retired — new streams use new connections, and existing streams are closed when they become idle or their own timeout expires.Helps with CGNAT but breaks long-lived protocols like SSH.Equivalent CLI flag: --tunnel-timeout

"tunnel-timeout": 1800

idle-timeout

integer

default:"600 (300 on Android)"

Maximum idle time for a tunneled stream in seconds. Streams idle beyond this threshold are forcibly closed to enable timely cleanup of retired connections.Equivalent CLI flag: --idle-timeout

"idle-timeout": 600

extra-headers

string

Extra HTTP headers to append to every proxy server request. Separate multiple headers with CRLF.Equivalent CLI flag: --extra-headers

"extra-headers": "X-Custom-Header: value"

host-resolver-rules

string

Statically maps a domain name to an IP address, bypassing DNS resolution for that hostname.Equivalent CLI flag: --host-resolver-rules

"host-resolver-rules": "MAP proxy.example.com 1.2.3.4"

resolver-range

string (CIDR)

default:"100.64.0.0/10"

The IP address range allocated by the built-in DNS resolver (active when using the redir listen protocol).Equivalent CLI flag: --resolver-range

"resolver-range": "100.64.0.0/10"

log

string

default:"(none — no logging)"

Path to a log file. Set to an empty string "" to print logs to the console instead of a file. Omitting this field entirely disables all logging for privacy.Equivalent CLI flag: --log

"log": "/var/log/naive.log"

log-net-log

string

Path to save a Chromium NetLog capture. View the file at https://netlog-viewer.appspot.com/.Equivalent CLI flag: --log-net-log

"log-net-log": "/tmp/netlog.json"

ssl-key-log-file

string

Path to save TLS session keys in NSS Key Log format for Wireshark inspection.Equivalent CLI flag: --ssl-key-log-file

"ssl-key-log-file": "/tmp/ssl-keys.log"

no-post-quantum

boolean

default:"false"

Set to true to disable X25519Kyber768 post-quantum key agreement. Post-quantum is enabled by default. Only disable this if you encounter compatibility issues with your server.Equivalent CLI flag: --no-post-quantum

"no-post-quantum": false

Complete Examples

Full config (all fields)
Minimal — HTTPS transport
Minimal — QUIC transport
Multiple listeners
Proxy chain

A reference config showing every available field:

{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "https://user:pass@example.com",
  "insecure-concurrency": 1,
  "tunnel-timeout": 1800,
  "idle-timeout": 600,
  "extra-headers": "X-Custom-Header: value",
  "host-resolver-rules": "MAP proxy.example.com 1.2.3.4",
  "resolver-range": "100.64.0.0/10",
  "log": "",
  "log-net-log": "/tmp/netlog.json",
  "ssl-key-log-file": "/tmp/ssl-keys.log",
  "no-post-quantum": false
}

The simplest useful config: a local SOCKS5 proxy that tunnels traffic over HTTPS (HTTP/2 CONNECT with TLS):

{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "https://user:pass@example.com"
}

Same as above but using QUIC (HTTP/3 CONNECT) as the transport, which may perform better on lossy networks:

{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "quic://user:pass@example.com"
}

Two listeners — one SOCKS5 and one HTTP — each routed to a different upstream server:

{
  "listen": [
    "socks://127.0.0.1:1080",
    "http://127.0.0.1:8080"
  ],
  "proxy": [
    "https://user:pass@server1.example.com",
    "https://user:pass@server2.example.com"
  ]
}

The listen and proxy arrays must be the same length. Each listener is paired with the proxy at the same index.

Route traffic through two sequential HTTPS hops before reaching the internet:

{
  "listen": "socks://127.0.0.1:1080",
  "proxy": "https://user:pass@hop1.example.com,https://user2:pass2@hop2.example.com"
}

QUIC proxies cannot follow TCP-based proxies in a chain, and you must ensure there are no loops. SOCKS proxies do not support chaining.

Field Summary Table

JSON Key	CLI Flag	Type	Default
`listen`	`--listen`	string \| string[]	`socks://0.0.0.0:1080`
`proxy`	`--proxy`	string \| string[]	direct (none)
`insecure-concurrency`	`--insecure-concurrency`	integer	`1`
`tunnel-timeout`	`--tunnel-timeout`	integer (s)	`1800` (`600` Android)
`idle-timeout`	`--idle-timeout`	integer (s)	`600` (`300` Android)
`extra-headers`	`--extra-headers`	string	—
`host-resolver-rules`	`--host-resolver-rules`	string	—
`resolver-range`	`--resolver-range`	string (CIDR)	`100.64.0.0/10`
`log`	`--log`	string	— (no logging)
`log-net-log`	`--log-net-log`	string	—
`ssl-key-log-file`	`--ssl-key-log-file`	string	—
`no-post-quantum`	`--no-post-quantum`	boolean	`false`

CLI Reference

Internals

NaïveProxy JSON Configuration Reference: All Fields

Config File Basics

Config File Fields

Complete Examples

Field Summary Table

Build docs developers (and LLMs) love

CLI Reference

Internals

Documentation Index

​Config File Basics

​Config File Fields

​Complete Examples

​Field Summary Table

Build docs developers (and LLMs) love

Config File Basics

Config File Fields

Complete Examples

Field Summary Table