Tutorial October 9, 2026

Clash TUN Mode for Developers: Proxy Git and CLI Tools

Route developer terminal traffic with Clash TUN. Set up Git, SSH, and Homebrew access, then check DNS, routing, and common connection issues.

Docker Proxy GitHub Acceleration Advanced Config YAML

1. Why terminal traffic needs a different plan

A browser working through Clash does not prove that Git, SSH, Homebrew, or an IDE terminal is using the same route. These tools run as separate processes, may inherit different environment variables, and often open connections through libraries that do not consult the operating system’s ordinary proxy settings. A command can therefore fail while a browser succeeds—or appear to work only because one process happened to reuse a connection opened earlier.

Mihomo TUN mode addresses one part of that problem by creating a virtual network interface and capturing IP traffic at the system level. When TUN is enabled and its routes are installed correctly, an application does not need to know that Clash exists: its packets can be handed to Mihomo, where the active rules decide whether to use a proxy group or DIRECT. This is useful for tools that ignore HTTP_PROXY and HTTPS_PROXY, and for child processes launched by editors, build systems, or package managers.

TUN is not a magic “proxy every command” switch. It depends on operating-system permissions, interface routing, DNS behavior, and a working Mihomo profile. A request may still bypass the tunnel if the route was not installed, go to the wrong policy if the rule order is broad, or fail before routing if DNS returns an unusable address. Conversely, a captured packet can be sent directly if a matching rule selects DIRECT. Think of the setup as three separate decisions: capture the connection, resolve its destination, then choose its route.

This guide is for developers who need a repeatable workstation setup, not a way to bypass company controls. Before routing source code, credentials, package downloads, or API traffic through a third-party node, check your organization’s security and data-handling rules. A proxy operator can observe connection metadata and may terminate or inspect traffic if a client or certificate setup is unsafe. Keep private keys and access tokens out of shared configuration files, and never publish a full profile containing subscription URLs or credentials.

The examples use Clash Verge Rev with a Mihomo-compatible profile, but the same checks apply to other Mihomo clients. Interface labels vary by operating system and application version; use the client’s own TUN controls rather than assuming that a YAML fragment alone has enabled packet capture. Start with a single test machine and one known destination, then expand the policy only after you can explain which rule matched and why.

2. Enable TUN without losing control

Before switching TUN on, confirm that the profile loads successfully in Mihomo and that at least one proxy group has a selectable, reachable node. Save a copy of the current configuration, note the present system proxy state, and make sure you know how to stop the client if a route change interrupts remote access. On desktops, TUN commonly requires elevated permissions or an operating-system network extension approval. Grant only the permissions requested by the client, and restart or reauthorize it if the system explicitly requires that step.

A typical Mihomo profile may contain settings like the following. This is a starting point, not a complete profile: merge it with the DNS, proxy, and rule configuration you already use, and check the client’s supported options before copying it verbatim.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  strict-route: true

The names describe different responsibilities. enable turns on TUN support; auto-route asks Mihomo to install routes; auto-detect-interface helps it identify the outbound network interface; and strict-route can make routing behavior more consistent on supported platforms. The stack setting selects a packet-processing implementation. Do not copy a stack choice from a guide written for a different operating system without testing it: performance, compatibility, and available options can vary by platform and Mihomo build.

After applying the profile, check the client’s connection or log view for TUN initialization errors and verify that the operating system shows the expected virtual interface or route. If the client reports a permission error, solve that first; editing domain rules will not fix an interface that never started. If you use a laptop with Wi-Fi and Ethernet, confirm which physical interface is active and test again after changing networks. A configuration that works at home may need a different route-detection behavior on a dock, hotspot, or corporate LAN.

Decide deliberately what should happen to traffic that does not match a specific rule. A common policy is to send selected developer services through a proxy group and keep known internal services on DIRECT, while a final catch-all rule handles the remaining traffic. The right fallback depends on your profile and network requirements; do not assume an unmatched connection will use the route you intended. Also avoid adding a rule that sends all private address ranges through a public relay: internal Git servers, build caches, and local services usually need a direct or corporate-approved path.

3. Route Git, SSH, and Homebrew intentionally

TUN can capture the connection without any per-tool proxy variables, but Mihomo still needs a policy for the destination. For Git over HTTPS, inspect the actual remote URL and test the hostname shown in the error or connection log. Git hosting commonly involves more than one domain: repository access, raw files, release assets, and large-file storage may be served separately. Add only the hostnames your workflow actually needs, and put specific rules before broad rules that would otherwise match first.

For example, a profile may route a known Git service through a named proxy group while leaving an internal code host direct. Replace the example group name with one that exists in your own profile, and verify the syntax supported by that profile’s rule format.

rules:
  - DOMAIN-SUFFIX,github.com,DeveloperProxy
  - DOMAIN-SUFFIX,githubusercontent.com,DeveloperProxy
  - DOMAIN,git.internal.example,DIRECT
  - MATCH,DefaultRoute

This example is intentionally narrow. It is not a universal GitHub allowlist, and your organization may use a mirror, single sign-on provider, or self-hosted Git service. Review the connection log during a clone, fetch, and release download; if a request to a different host fails, confirm that it belongs to the workflow before adding a rule. A broad rule for every code-hosting or cloud domain can unintentionally route private services through an external node.

SSH needs separate attention because an SSH remote usually connects to a host and port directly, rather than sending an HTTPS request that follows Git’s HTTP proxy settings. If TUN captures the TCP connection, a domain rule can still choose its route. But if your network blocks the SSH port or you want an explicit SSH-level proxy, configure that separately and test it without changing the route for all Git traffic. Some providers offer SSH over port 443, but the exact host and availability depend on the provider; do not assume that changing the port alone will work.

For an explicit SOCKS-based SSH route, OpenSSH can use a local SOCKS listener through a proxy command, if your Clash client exposes one and the required helper is installed. The following is illustrative; replace the address and port with the listener configured on your machine.

Host github.com
  HostName github.com
  User git
  ProxyCommand nc -x 127.0.0.1:7891 -X 5 %h %p

Do not enable both an explicit per-application proxy and a TUN-based policy without knowing how they interact. Nested routing can make failures harder to diagnose, and a tool may try to reach the local listener through a route that is itself unavailable. Test with ssh -T and inspect the client log. If the SSH connection succeeds but Git still fails, compare the remote URL: a repository configured with an HTTPS URL does not use the SSH host block.

Homebrew on macOS and Linux can also contact several hosts during one operation, including its Git remotes, API endpoints, and bottle or source download locations. A successful brew update does not necessarily confirm that a later package download follows the same path. Use Mihomo’s connection log to identify the destination of each failed request, then add a narrowly scoped rule if needed. Avoid hard-coding a long list of guessed CDN domains; providers can change delivery hosts, and a stale allowlist can create intermittent failures that look like package-manager bugs.

Environment variables remain useful when a particular command or runtime does not use the route you expect, or when you want a temporary, easy-to-remove test. They are not a substitute for verifying TUN. A shell’s variables may not reach a graphical IDE, a background service, or a build daemon started before the change. Check the process environment in the context where the failing command actually runs, and remove temporary proxy exports after testing if they are no longer part of the intended setup.

4. Check DNS, rules, and the actual route

DNS is a frequent source of apparent routing failures. A terminal may resolve a hostname through the system resolver while Mihomo is configured to use its own DNS settings; a browser can also reuse a cached address that differs from a fresh command-line lookup. If the profile uses fake-IP mode, applications may see synthetic addresses that Mihomo later maps back to domain names. This allows domain rules to work for captured connections, but can complicate debugging when another resolver, local cache, or VPN client participates in the lookup.

When a hostname fails, compare several observations rather than changing DNS at random. Check whether the system can resolve it, whether the Clash log records a DNS request, what destination appears for the connection, and which rule and policy were selected. If you have recently changed DNS mode, restart the affected application and clear its own cache where appropriate. A browser’s cached connection, an IDE daemon, and a terminal process may all retain state independently. Avoid mixing unrelated DNS overrides into the profile until you can reproduce the failure with one resolver path.

Rule order matters because Mihomo evaluates rules in sequence and uses the first matching rule. A broad rule placed above a developer-specific rule can silently override the route you intended. For example, a general geographic or domain-suffix rule may match a repository host before your explicit proxy choice is reached. Put precise internal and developer rules above broader categories, then check the connection detail in the client to confirm the selected rule. The log is more reliable than inferring behavior from a successful browser tab.

Use a small, repeatable test matrix instead of testing only one command. Try a DNS lookup, an HTTPS request to a known public endpoint, a Git fetch, an SSH handshake if you use SSH remotes, and a Homebrew metadata or package operation. Record the exact command, time, network, resolved address if available, and Mihomo policy shown in the log. If only one tool fails, investigate that tool’s URL, environment, and connection method before changing global TUN settings. If every tool fails after TUN activation, return to interface permissions and route installation.

Symptom Likely area to inspect First useful check
Browser works, terminal times out Process environment, TUN capture, or a different hostname Run the command again while watching Mihomo’s connection log
Git HTTPS works, SSH fails SSH port, remote URL, or explicit SSH proxy configuration Check the remote URL and test an SSH handshake separately
One package downloads, another stalls Separate API, Git, or artifact hosts Identify the failed destination instead of adding a wildcard rule
Host resolves but connection is refused Selected route, remote port, or service availability Confirm the matched rule and test the same host through its intended path
Internal services stop working Private address routing or an overly broad proxy rule Check whether the internal hostname or address should use DIRECT or a corporate VPN

IPv6 deserves its own check on networks that provide it. A command may prefer an IPv6 address while a proxy node or routing policy only behaves as expected over IPv4. Do not disable IPv6 as a reflex: first establish whether the failure is specific to IPv6 and whether your network policy permits changing it. Likewise, exclude local DNS names and private services from public proxy rules only when that matches your network design; “private” does not always mean “safe to bypass the corporate tunnel.”

5. Troubleshoot safely and keep the setup maintainable

If TUN does not start, troubleshoot from the bottom up. Confirm the client version and Mihomo core are compatible with the profile, validate the YAML indentation, and read the startup log for permission, interface, or route errors. Check that another VPN, endpoint security product, or virtual network adapter is not competing for routes. Change one setting at a time and restart the client after each change. If a corporate VPN is required for internal systems, coordinate the routing design with your administrator rather than trying random interface priorities that could interrupt access or expose traffic.

If TUN starts but a request still uses the wrong route, first identify the destination and the matched rule. If there is no connection entry, the application may be using a different network namespace, a stale connection, or an unexpected proxy environment. If the entry appears with the wrong policy, correct rule order or the selected proxy group. If the expected policy is shown but the connection fails, test the node and destination independently; a routing rule cannot repair an unavailable server, invalid credentials, or a remote service that rejects the request.

For command-line checks, keep tests simple and avoid exposing sensitive values in logs or shared issue reports. A verbose Git trace can include repository URLs, usernames, or authentication details; redact them before sharing. Do not paste subscription links, private keys, access tokens, or full configuration files into support channels. When a connection works only after exporting a proxy variable, note that as a diagnostic result, then decide whether that tool should use an explicit proxy permanently or whether TUN capture and policy should provide the route instead.

Teams benefit from documenting the tested behavior rather than just storing a snippet. Record the client and core versions, operating system, TUN settings, required proxy groups, relevant internal exceptions, and the commands used to verify Git, SSH, and package downloads. Keep environment-specific hostnames out of a shared public profile where possible, and review rules when a provider changes its endpoints. A short runbook prevents the next developer from treating a corporate DNS issue as a broken proxy—or copying a permissive wildcard rule into a laptop that handles production credentials.

Some conventional desktop VPN clients make browser access straightforward but offer fewer visible controls for separating internal Git, public repositories, SSH, and package artifacts. Per-tool proxy variables provide finer control, yet they are easy to miss in IDE subprocesses and long-running build daemons. With Clash TUN, Mihomo can capture system traffic while explicit rules keep internal services on their approved path and send selected developer endpoints through a chosen proxy group. If that combination fits your network policy, Download Clash and test the route with one repository before expanding it across your toolchain.

Ready to get started?

Set up a Mihomo-compatible client, verify TUN capture, and route developer tools with rules you can inspect.