Misc Options
[General]
ipv6 = true
loglevel = notify
skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local
tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12
tun-included-routes = 192.168.1.12/32
Common Options
Enable full IPv6 support (Default: true)
ipv6 = true
When set to false, DNS answers lose their AAAA records and IPv6 hints, and the fake-IP pool answers no AAAA; the rest of the answer — its A records and any other records — is kept.
loglevel (Default: warning)
loglevel = notify
One of none, fatal, warning, notify, info or verbose. It's not recommended to enable verbose in daily use because this will slow down the performance significantly.
skip-proxy
skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local
In iOS and tvOS version, a hostname entry is added to the tunnel's proxy exception list, so connections to it are handled by Chute TUN instead of Chute proxy; an IP address or CIDR entry additionally becomes an excluded route of the tunnel, so traffic to that range leaves the tunnel entirely rather than being handled by Chute TUN. Chute Android does the same in VPN mode: while System HTTP Proxy is on, hostnames, * wildcards and IPv4 addresses join the exclusion list of the proxy the VPN hands to apps, and on Android 13 and later every IP address or CIDR entry becomes an excluded route of the VPN — a bare address as a /32 or /128 route; loopback entries are left out, since loopback traffic never enters the tunnel. In macOS version, these settings will be applied to system when "Set as System Proxy" is enabled. While Enhanced Mode is on, IP address and CIDR entries also stay out of the tunnel, in either Enhanced Mode type, as on iOS — see Excluded Routes; with the PacketTunnel type, the same exceptions also apply to the HTTP/HTTPS proxy the tunnel carries while System Proxy is on. This option is used to fix compatibility problems with some apps.
- To specify a single domain, enter the domain name - for example, apple.com.
- To specify all websites on a domain, use an asterisk before the domain name - for example, *apple.com.
- To specify a specific part of a domain, specify each part - for example, store.apple.com.
- To specify hosts or networks by IP addresses, enter a specific IP address such as 192.168.2.11 or an address range, such as 192.168.2.* or 192.168.2.0/24.
Notice: If you enter an IP address or address range, you will only be able to bypass the proxy when you connect to that host using that address, not when you connect to the host by a domain name that resolves to that address.
Proxy Server Listening
interface = 127.0.0.1
port = 8118
socks-interface = 127.0.0.1
socks-port = 8119
interface / port control the listening address and port of the HTTP proxy server (default 127.0.0.1:8118). socks-interface / socks-port control the SOCKS5 proxy server (default 127.0.0.1:8119). On iOS and tvOS the two listeners run only when they are bound to every interface — with allow-wifi-access = true, an interface / socks-interface of 0.0.0.0, or on iOS the app's Allow LAN Connections switch — so with the default 127.0.0.1 nothing listens on these ports there; Chute Mac and Chute Android always start them. Serving other devices is Chute Pro on every platform: without it, a non-loopback address is ignored and the bind stays on 127.0.0.1, so on iOS and tvOS the listeners do not start at all.
When a port is taken, the server moves on to the next one up, trying up to 20 ports in all, starting with the configured one; if none of them is free, that server does not start and the rest of the engine keeps running. The port actually in use is the one GET /api/status reports as http_port and socks_port, and the one the web console's Overview page shows. The SOCKS5 server's UDP relay binds a port of its own and does not move with the TCP listener: after a move it can still be on the configured port, or on another port altogether. The UDP ASSOCIATE reply always names the port the relay actually uses, so a client that sends its datagrams to the address in that reply, as RFC 1928 requires, is not affected.
Give port and socks-port a value from 1 to 65535: they are not range-checked when the configuration loads, and with a value outside that range the server either does not start or ends up listening on another port. Written through http-listen / socks5-listen, such a port is a configuration error.
The HTTP proxy server carries one exchange per connection for a plain http:// request: each response goes out with Connection: close and the connection closes after it, so the client sends its next request on a new connection. A request pipelined behind the first is dropped, and the client sends it again on the new connection. An authentication scheme that needs several round trips on the same connection, such as NTLM or Negotiate, cannot complete through it. A CONNECT tunnel that is not decrypted is not affected. A WebSocket upgrade keeps its connection: after the 101 response, data passes unchanged both ways.
Compatibility aliases:
doh-serveranddoh-serviceare accepted as aliases ofdoh;http-listen/socks5-listen(e.g.0.0.0.0:6152,[::]:6153, or a bare port) are mapped onto the interface/port settings above. A wildcard listen host (0.0.0.0,::, or*) also setsallow-wifi-access = true.
Inbound Proxy Authentication
http-auth = username:password
Requires clients to authenticate before using Chute's HTTP and SOCKS5 proxy servers. The line may be repeated to allow multiple credentials.
The HTTP proxy answers a request without valid credentials — a plain request or a CONNECT — with 407 Proxy Authentication Required and Proxy-Authenticate: Basic realm="KLNEKit", then closes the connection. The SOCKS5 server takes the same credentials through SOCKS5 username/password authentication and closes a connection that does not offer it or fails it.
Bypass System Requests
bypass-system = true
When enabled, Chute appends a fixed list of 18 Apple hostnames — push, iCloud gateway, captive-portal check, OCSP and similar — to skip-proxy, and appends IP-CIDR,17.0.0.0/8,DIRECT,no-resolve after your rules, just before FINAL — so a rule of yours that matches 17.0.0.0/8 first still wins. There is no process-based matching: the option is that fixed host and address list, not a filter on which process made the request.
Default:
true.
Always Real IP
always-real-ip = *.example.com, tracker.example.org
When Chute serves fake IP addresses for hijacked DNS queries (see hijack-dns), hostnames matching this comma-separated list are always answered with their real resolved IP addresses instead. Wildcards are supported. always-ip-address (Shadowrocket's spelling) is read as this key: a boolean value (true, yes, on, 1) means every host and is rewritten to always-real-ip = *; false is dropped; any other value is read as a host list. The configuration is saved with the always-real-ip spelling.
Read the System Hosts File
read-etc-hosts = false
Whether the system hosts file is read into the [Host] table. Set it to false to ignore that file; a change takes effect on reload. See Local DNS Mapping.
Default:
true.
Interrupt Existing Connections
interrupt-exist-connections = true
When enabled, a change of route closes the existing connections that were made under the old one, so they use the new route immediately rather than lingering on the old one until they end. These changes count:
- A policy group choosing another member — on its own (URL Test, Fallback, SSID) or by manual selection. The connections that were using the member it left are closed. A Load Balance group spreads connections over its members and never counts as switching.
- A change of the policy selected for Global mode, which the built-in
PROXYfollows: the connections Global mode sent to the old policy, and those that reached it throughPROXY, are closed. - Switching the outbound mode between Rule, Global and Direct: every connection is closed.
- A reload that changes the DNS servers,
[Host], the policies, policy groups or proxy providers, or the rules or rule sets: every connection is closed.
This applies to every group a connection passes: the group its rule names, a group nested in it, the upstream group of a chained policy (underlying-proxy), and a relay group's member groups.
After a group switch or a change of the Global mode policy, each affected connection is closed gracefully with a 3-second timeout before being force-closed; a mode switch or a reload closes them at once. An ordinary UDP flow is not closed by any of these. Rules added through /api/rules/user are not governed by this option: by default they close the connections they route elsewhere whether it is on or off.
Default:
false. This is a global setting — it affects all policy groups.
Network Framework (macOS / iOS / tvOS)
network-framework = true
Enable Apple Network.framework for outbound connections. Using Network.framework can provide better performance and modern TLS stack integration on supported platforms.
Default:
trueon macOS,falseon iOS and tvOS.
Exclude Simple Hostnames
exclude-simple-hostnames = true
When enabled, requests to simple hostnames (single-label names without a dot, e.g. localhost) bypass proxy rules and are resolved locally. This helps avoid unnecessary DNS lookups for local network names. This is the macOS system proxy's own "Exclude simple hostnames" setting: Chute Mac writes it into the system proxy configuration, so it applies to applications that follow the system proxy and to nothing else — not to Enhanced Mode or TUN traffic. On iOS and tvOS it is written into the tunnel's proxy settings in the same way, so a simple hostname is handled by Chute TUN instead of Chute proxy, as a hostname in skip-proxy is. Chute Android does not use it.
On Chute Mac, a one-time migration enables this option by default on first run; an explicit user off setting is respected.
Default:
false.
Disable Database Record
disable-db-record = true
When enabled, Chute stops writing traffic records to the local database. This can improve performance and reduce storage usage, but traffic history will not be available in Chute Dashboard.
Default:
false.
Menu Bar Speed Display (Mac Only)
menu-bar-show-speed = true
When enabled, Chute Mac shows the current upload and download speed in the menu bar.
Parsed but not effective in the current engine — nothing in Chute Mac reads the key. The menu bar speed is toggled from the menu item Show Connection Speed, which is stored in the app's own settings. The key is still written back when the configuration is saved.
Hijack Other DNS Servers
hijack-dns = 8.8.8.8:53
By default, Chute only returns fake IP addresses for DNS queries sent to Chute DNS address (198.18.0.2). Queries which are sent to standard DNS will be simply forwarded.
Some devices or softwares always use a hardcode DNS server. (For example, Google Speakers always use 8.8.8.8). You may use this option to hijack the query to get a fake address.
You may usehijack-dns = *:53to hijack all DNS queries.
An entry without a port means port 53, so hijack-dns = 8.8.8.8 is 8.8.8.8:53. An entry that cannot be read is skipped with a notice; the rest of the line still applies.
Fake IP is available on Apple TV too (tvOS 17 and later). It had been disabled there; verification on a device is still in progress.
Excluded Routes
tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12
Chute VIF can only process TCP and UDP protocols. Use this option to bypass specific IP ranges to allow all traffic to pass through.
Notice: This option applies to the iOS and tvOS packet tunnels, where the ranges become excluded routes of the tunnel's IP settings, and to Chute Android on Android 13 and later, where they become excluded routes of the VPN — Android 11 and 12 have no API for excluded routes, so the ranges are ignored there. Requests handled by Chute Proxy Server will not be affected. Combine 'skip-proxy' and 'tun-excluded-routes' to make sure that certain HTTP traffic bypasses Chute.
On macOS it applies in both Enhanced Mode types, and what stays out of the tunnel is the same list the iOS and tvOS tunnels keep out: the ranges of this option, the ranges of
bypass-tunand the IP address and CIDR entries ofskip-proxy— hostname entries are not routes and play no part. With the PacketTunnel type the ranges become excluded routes of the tunnel's IP settings, as on iOS. With the Helper utun type the helper leaves them out of the routes it points at the utun, so traffic to them follows the system's ordinary routes; for IPv6 the helper points only2000::/3at the utun, so only IPv6 ranges inside2000::/3change anything there. IPv6 ranges matter only while the tunnel carries IPv6 (ipv6 = true). An entry with a prefix length of0(0.0.0.0/0,::/0), or one that overlaps loopback (127.0.0.0/8,::1) or the tunnel's own subnets (198.18.0.0/15,fd12:1:1:1::/64), is skipped and noted in the log — so the127.0.0.1thatskip-proxyusually contains is simply skipped. Atun-included-routesentry more specific than an excluded range still wins, since routes are chosen by prefix length. A changed list takes effect when the configuration is reloaded.This option might cause a system error ENOMEM (Cannot allocate memory). It seems a bug in iOS system. Please do not use this option if possible.
Included Routes
tun-included-routes = 192.168.1.12/32
By default, the Chute VIF interface will declare itself as the default route. But since the Wi-Fi interface has a smaller route, some traffic may not go through the Chute VIF interface. Use this option to add a smaller route.
The reason a default route is not enough: the system picks a route by prefix length, not by order. The physical interface's own on-link subnet — 192.168.1.0/24, say — is more specific than the tunnel's 0.0.0.0/0, so that traffic never reaches Chute. An entry here installs a still more specific route and wins. The routes are added on top of the default one and never narrow what the tunnel captures.
Note: Avoid listing the private ranges (
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16) wholesale. It is normally unnecessary and can upset the system's own routing; Chute honours such an entry but logs a warning — except under the Network Extension flavour of Enhanced Mode on macOS, which honours it without one. The usual reason to use this option is reaching a range another VPN app's tunnel owns.Note: An entry that would cut the branch Chute sits on is refused with the reason in the log: loopback, the VIF's own subnets (
198.18.0.0/15andfd12:1:1:1::/64), link-local, multicast, broadcast, and a prefix length of0. The helper-utun flavour of Enhanced Mode on macOS also refuses an entry that covers the current default gateway. Under the Network Extension flavour the reason goes to the system log rather than to Chute's.Note: On iPhone the system decides local-network capture separately. A local subnet listed here is honoured only when Include Local Networks is also on in the app's settings — a switch that can be turned on only while Include All Networks is on; a range owned by another app's tunnel needs no such switch. Chute tvOS shows the same switches but does not apply them to the tunnel. On macOS the routes are installed directly and no such gate applies.
Note: On macOS the helper-utun flavour of Enhanced Mode installs these routes when the interface is attached, so a changed list re-attaches the interface on reload. This option needs helper version 0.8.6 or later — after updating Chute, approve the helper reinstall prompt once, or the helper-utun flavour reports that the helper is not running.
Protocol Sniffing
sniffing-enabled = true
sniffing-timeout = 100
Chute can detect the actual protocol of a connection by inspecting the initial bytes. This enables rules like PROTOCOL,TLS,Proxy to work correctly even for non-HTTP inbound connections.
sniffing-enabled (Default: false)
sniffing-enabled = true
Enable protocol detection for TCP connections. In Enhanced Mode the same switch lets an HTTP/3 (QUIC) flow to a bare IP address be matched by name: Chute reads the server name from the QUIC ClientHello, DOMAIN-type rules see that name instead of the address, and every later packet of the flow follows the verdict of the first. A ClientHello too large for one packet — common with post-quantum key exchange — is reassembled per flow from the Initial packets that carry it, up to a reassembled hello of 16 KiB, so its name is read as well. While the rest of the hello is still coming, the flow's datagrams are held rather than sent by their bare address, and they go out together behind the name once it is read — so the first fragment of a split hello no longer takes a different route from the rest of it. The backstops are a one-second wait, eight datagrams or 16 KiB held per flow, and 64 flows assembling at once; a flow past any of these, or one whose Initial packets never complete the ClientHello, is matched by address as before.
For a connection to a real address, the name the client states itself — the TLS SNI or the HTTP Host — is what the rules see, even when Chute's DNS cache already holds a name for that address: the cache keeps one name per address, the last that resolved to it, and behind a shared address that may be another site's. The cached name is used when nothing can be read from the connection. A request written for an HTTP proxy — CONNECT, or one whose target is a full URL — is still detected as HTTP, but the host it names is where that proxy is to go next, not this connection's name; the connection keeps the cached name or the address. A protocol in which the server speaks first gives no name to read: connections to ports 21, 22, 23, 25, 110, 119, 143, 587, 2222, 2525, 3306 and 5900 skip detection and are connected at once, and on any other port such a protocol waits out sniffing-timeout before it is connected.
sniffing-timeout (Default: 100ms)
sniffing-timeout = 200
Maximum time in milliseconds to wait for the initial data to determine the protocol. Increase this value if protocol detection fails on slow connections.
Block QUIC
block-quic = auto
Controls whether Chute rejects detected QUIC traffic, including HTTP/3. QUIC runs over UDP and cannot be decrypted by Chute's HTTP MitM. Rejecting QUIC can prompt compatible clients to retry over TCP, allowing TCP-based proxy handling and, when configured, HTTPS decryption to apply.
| Value | Behavior |
|---|---|
off |
Do not apply global QUIC blocking (default). Detected QUIC traffic follows the normal routing rules. |
on |
Reject every detected QUIC flow, including traffic routed to DIRECT. |
auto |
Reject detected QUIC only when the final outbound policy is a proxy. Traffic routed to DIRECT is allowed; traffic routed to REJECT remains rejected by that rule. |
all |
Surge's spelling of on. |
all-proxy, per-policy |
Surge's spellings, both read as auto — Chute has no per-policy QUIC blocking, so per-policy blocks QUIC on every proxied flow. The word you wrote is kept when the profile is saved. |
For traffic entering through TUN, Chute replies to a rejected QUIC flow with an ICMP/ICMPv6 Port Unreachable message so compatible clients can fall back without waiting for a QUIC timeout.
A rejected QUIC flow is recorded with
REJECTas its policy, whichever policy the rule chose.QUIC detection for
block-quicis automatic and does not requiresniffing-enabled;sniffing-enabledcontrols protocol sniffing — TLS on TCP, and the server name of a QUIC flow. Use aPROTOCOL,QUIC,...rule when you need rule-based handling of individual QUIC flows.
Answer ICMP in the Tunnel
icmp-auto-reply = false
An ICMP echo request that enters the tunnel — IPv4 or IPv6 — is answered by Chute itself: the reply is synthesised locally and nothing is sent to the target. Every destination therefore answers, an address a rule would REJECT and a host that is down included, so a ping that succeeds inside the tunnel says nothing about whether the target is reachable. Set this to false to stop answering: the request is then relayed out of the device, but its reply never comes back through the tunnel, so the ping is never answered.
Default:
true. Applies to traffic arriving through TUN; ICMP is never proxied.
Bypass TUN
bypass-tun = 192.168.0.0/16, 10.0.0.0/8
Similar to skip-proxy, but works at the TUN/VIF routing level. Connections to these IP ranges will bypass the TUN interface entirely and go through the system network stack directly.
Note: This option applies to the iOS and tvOS packet tunnels, where its ranges join
tun-excluded-routesas excluded routes of the tunnel, and in the same way to Chute Android on Android 13 and later (Android 11 and 12 ignore it). On macOS its ranges jointun-excluded-routesin both Enhanced Mode types — see Excluded Routes.
Show Error Page for Reject
show-error-page-for-reject = true
When enabled, Chute returns a user-friendly error page for rejected requests. This applies only to a request that arrived through the HTTP proxy inbound; with the option off, such a request is answered with HTTP/1.1 503 Service Unavailable instead. A rejected request from any other inbound is dropped either way.
Default:
false.
Optimistic DNS
optimistic-dns = false
When enabled, a cached record whose TTL has passed is still returned at once while it is looked up again in the background. This reduces connection latency at the cost of possibly returning stale DNS records. An expired record is only returned this way for a limited time: as long again as its own TTL, and no less than five minutes; after that the query waits for the upstream answer. With it off, a record whose TTL has passed is not returned and the query goes upstream; that answer refills the cache, so the next lookup is answered from it. When the device moves to another network, or the list of DNS servers changes, every cached record is treated as expired. It also governs, on every platform, whether the tunnel dials several of a name's addresses at once.
Default:
true. Setoptimistic-dns = falseto disable.
Allow Wi-Fi Access PRO
allow-wifi-access = true
Lets other devices on the same network reach Chute's HTTP and SOCKS5 proxy ports, by widening both listeners to 0.0.0.0. Surge-style configurations — and the sing-box importer's allow-lan mapping — carry only this flag and leave interface at its 127.0.0.1 default, which is why the flag widens the bind address itself. This is a Chute Pro feature: without it the flag and a wildcard interface are ignored, both listeners stay on 127.0.0.1, and on iOS and tvOS they therefore do not start.
The apps also have a switch for this, Allow LAN Connections: on Chute Mac in the menu bar menu (LAN Connections in the menu bar panel), and in the Control Panel on Chute iOS and Chute Android; Chute tvOS has none. It starts in the state the configuration asks for, and moves both listeners to every interface or back to 127.0.0.1 for the current run only; on iOS, where the listeners run only on every interface, it also starts and stops them. Nothing is written to the configuration: the next start, or a reload that is accepted, goes back to what the configuration says. Turning it on needs Chute Pro; turning it off does not.
The flag and an explicit wildcard
interfaceare two spellings of the same intent, and Chute takes the union: a configuration that already writes0.0.0.0behaves exactly as before. Changing the flag rebinds both listeners, so withdrawing access takes effect on reload rather than at the next restart.These are the proxy ports, which have no authentication unless
http-authis set. On a network you do not control, set credentials as well.
Managed Configuration
#!MANAGED-CONFIG https://example.com/config.conf interval=86400 strict=false
A configuration whose first line is a #!MANAGED-CONFIG header is re-fetched from the URL automatically. The header's parameters and the update behavior are documented in Managed Configuration.
Replica / Traffic Recording PRO
replica = true
The replica key in [General] (replica = true) enables traffic recording; the [Replica] section filters what the Chute Dashboard displays — its keys are documented in Replica.
An active Chute Pro license is required as well on every platform: without it
replica = truecaptures nothing, and bodies from an earlier licensed run cannot be read back.
External Controller Access (Chute Dashboard)
external-controller-access = password@0.0.0.0:6155
Starts the remote control server used by Chute Dashboard. The value is password@host:port; a username may optionally precede the password (user:password@host:port). On iOS and tvOS, a companion USB channel is opened on port + 1 (not on macOS). Connecting it is described on the Chute Dashboard page.
HTTP Control API and Web Console
This is documented on its own page: HTTP Control API and Web Console.
Proxy Test URL
[General]
proxy-test-url = http://cp.cloudflare.com/generate_204
test-timeout = 3
proxy-test-url is the probe URL of every url-test, fallback and load-balance group that does not set its own url, and test-timeout (seconds) the timeout of every such group without a timeout. Groups keep following these keys after the configuration is saved; only a url or timeout written on the group line overrides them. An invalid proxy-test-url is a configuration error. internet-test-url is used by the Web Console's direct Internet test, fetched without a proxy; when omitted, the engine uses its built-in success URL.
UDP Through a Policy Without UDP
udp-policy-not-supported-behaviour = DIRECT
What happens to a UDP datagram whose policy cannot relay UDP, such as a plain HTTP proxy: REJECT (the default) drops it; DIRECT sends it directly instead. block-quic is decided first, on the policy the rule chose: with block-quic = auto, QUIC headed for a proxy that cannot relay UDP is rejected rather than sent directly. Other UDP still falls back to DIRECT. UDP of a chained policy that cannot go through its upstream is handled the same way, and so is a DoQ or DoH3 upstream that follows the outbound mode into a policy without UDP: REJECT skips that upstream, DIRECT asks it directly.
Front Proxy
[General]
global-underlying-proxy = Airport
Sends every proxy policy that has no underlying-proxy of its own through the named policy or group — what Shadowrocket calls a front proxy (前置代理), which it sets only in its app. The policies of proxy providers are included. Left as they are: every policy a connection through the front policy itself can pass — its members, their upstreams and the hops of a relay among them — so the front policy never runs through itself; a policy that writes underlying-proxy=DIRECT, which opts out; policy groups, whose members decide; and DIRECT, REJECT and TAILSCALE. Leave the key out, or write DIRECT, to turn it off. A name that is not defined refuses every policy it would cover rather than letting it connect directly.
close-if-proxy-chain-missing (Shadowrocket) is read and written back when the profile is saved. Chute always does what its true does: a chained policy whose upstream is missing is refused. false — Shadowrocket's default, which skips the missing hop and connects to the node directly — is not followed, and a notice says so once.
Client Fingerprint
global-client-fingerprint = chrome
Sets the TLS client fingerprint for every policy that does not carry its own fingerprint, the policies a proxy provider supplies included. A policy's own value always wins, so this is a default rather than an override.
Supported values are chrome, firefox, safari and ios, plus edge, 360,
qq, android and random, which are all handled as Chrome, and the other
names listed under fingerprint.
An unrecognised value is ignored with the warning Ignoring unsupported global-client-fingerprint '<value>',
and the platform TLS stack is used.
Default: empty, meaning the platform TLS stack. It always reaches ShadowTLS and AnyTLS policies, and reaches Trojan, VMess and VLESS ones that set
tls=trueorreality=true, and Shadowsocks ones that set bothws=trueandtls=trueor that setshadow-tls-password; a policy on the gRPC transport without REALITY needstls=truewritten as well. ShadowsocksR policies never read it.