Node HandbookNODE HANDBOOK中文
Proxy modes · TUN

System proxy or TUN: two different questions

Whether a request enters the client, and where it goes once inside, are separate questions. Most confusion — “global mode is on, yet this app still fails” — comes from merging them.

Node Handbook editorial team ·

What each mode changes

System proxyTUN mode
What it modifiesWrites a local listening port into system or application proxy settingsCreates a virtual adapter and changes the routing table
What it coversOnly programs that actively read the proxy settingTraffic that goes through the IP stack, subject to routes and exclusions
Administrator rightsUsually not requiredRequires a service or driver installation
Typical failureA program does not read system settings and only honours environment variablesService not installed, adapter not created, default route taken over
After disablingSettings revert; programs go direct againVirtual adapter and routes are withdrawn
UDP / QUICMany implementations forward TCP only; UDP often bypassesUDP also enters the virtual adapter

That table explains most “I enabled the proxy but one program still does not use it” cases: the connection is fine, the program is simply outside the coverage of a system proxy.

Confirm which one is actually in effect

The commands differ by platform, but the conclusion has only two parts: is there a default route pointing at a proxy, and does the exit IP belong to the node.

PlatformCheck the proxy settingCheck the adapter or route
Windowsnetsh winhttp show proxy; Settings → Network & Internet → Proxy for the user-level valueipconfig for a TUN-style adapter; route print 0.0.0.0 for the default route
macOSscutil --proxyifconfig | grep utun; netstat -rn -f inet
LinuxDesktop proxy settings (independent of the shell)ip route, ip link show — TUN devices usually start with tun

Then compare the exit: curl -s https://ipinfo.io/ip. A node IP means that path was captured; a local public IP means it was not. If the same command gives different results in different terminals, you are looking at a coverage question, not a node question.

Browser works, terminal does not

A system proxy is a configuration that a program has to read. Default builds of curl and wget, self-built Go/Rust/Node clients and services running in the background generally do not. Two options follow:

  • Set HTTP_PROXY, HTTPS_PROXY and ALL_PROXY for the terminal, remembering that sudo and system services do not inherit your session environment.
  • Use TUN so capture happens at the system layer.

A second overlooked detail: under a system proxy, a browser may use QUIC over UDP 443. If the proxy forwards TCP only, some sites fail and then succeed on refresh. Disable QUIC in the browser before blaming the proxy.

Rules, global and direct are a different layer

Once traffic is inside the client, rule mode decides by rules, global mode uses the selected outbound, and direct mode goes direct. Check capture first, then routing. A global switch cannot pull in an application that was never captured.

CombinationWhat it doesWhen it misleads
System proxy + rulesOrdinary browsing with per-site routingWhen an app ignores the system proxy
System proxy + globalOnly affects apps that honour the settingWhen someone expects it to cover everything
TUN + rulesBroader capture, still rule-basedWhen an exclusion rule sends traffic direct
TUN + globalMore captured traffic uses the selected outboundWhen the expectation is “all traffic, no exceptions”

When not to enable TUN yet

  • The subscription has not updated successfully.
  • Nodes have not been verified with a real request.
  • A system proxy already meets the need.
  • Another VPN is running.

TUN adds a virtual adapter, routes, DNS and permission variables. Enabling it while the fault is still unlocated makes the fault harder to describe.

Record before enabling TUN

  • Client and core versions.
  • Current system-proxy state and DNS settings.
  • Whether IPv6 is enabled.
  • Whether other VPNs or security tools are active.
  • Grant permissions per the client's official documentation. Do not install drivers from unknown sources, and do not disable system security features by default to make a connection succeed.

If TUN breaks connectivity, how to get back

  1. Turn TUN off.
  2. Turn the system proxy off and quit the client fully.
  3. Confirm the system VPN or virtual adapter is no longer connected.
  4. Retest plain networking.
  5. If it is still broken, check whether service mode, on-demand rules or DNS overrides are enabled, then restore from your recorded values rather than clearing everything.

Capture or routing: which one is failing

  • Browser works, one application does not: likely a capture-scope question.
  • All captured applications fail on only some sites: likely a rule or target question.

Temporarily switching between rules and global is a valid contrast, but restore the original mode afterwards and record which step changed the result. A contrast that is not restored becomes a new, undocumented variable.

Scope

Based on the official concept documentation for the clients referenced. Interface wording differs by version and platform. This page is conceptual and does not include a configuration test on any specific build.