Set Up Clash TUN for Developer Terminal Traffic: Git, npm & Docker

Why Terminal Traffic Can Miss the Desktop Proxy

A browser may work through Clash while git, npm, pip, or Docker times out because those programs do not necessarily read the same proxy settings. A desktop client’s “System Proxy” option usually configures proxy settings for applications that honor the operating system’s HTTP or SOCKS proxy. Command-line tools, background services, containers, and applications using their own network stacks can behave differently.

There are two common ways to route command-line traffic. One is to configure proxy environment variables or application-specific settings. This is explicit and easy to inspect, but every tool must support the selected proxy protocol, and background services may not inherit a shell’s environment. The other is Clash TUN mode. With mihomo’s TUN interface enabled and routes installed, IP traffic from supported applications can enter the virtual interface without requiring each program to understand a proxy setting.

TUN is not a promise that every process on every platform will be captured. The operating system, client permissions, routing table, DNS configuration, containers, virtual machines, and firewall can all affect the path. TUN also does not decide which proxy node to use by itself: mihomo still applies its rules and proxy groups to connections it receives.

Check the Core and Prepare a Safe Test

TUN configuration in this guide assumes a client running a compatible mihomo core. “Clash” is used by many clients and core versions, but not every version supports the same fields or exposes the same controls. Open the client’s About, Core, or Runtime page and record the client version, core name, and core version before changing settings. Back up the active configuration or make a copy of the relevant override.

Start with a working configuration in rule mode and a proxy group that already has a known-good node. Confirm that the client can test or use that node before enabling TUN. If the proxy group is named differently in your configuration, use its actual name in any rules you add; a rule that points to a nonexistent group cannot route as intended.

1. Close or pause other VPN clients, network accelerators, and packet-capture tools for the initial test. Do not disable corporate security software or bypass a managed-device policy.
2. Record whether the desktop System Proxy setting is on, which proxy group is selected, and whether the connection panel shows successful browser traffic.
3. Make sure the active profile has valid proxy groups and rules. A subscription can appear in a client without being the selected active configuration.
4. Use a small, repeatable request first, such as checking a public package registry or fetching a known repository. Avoid testing with a large image pull or production deployment.
5. Keep the client’s connection log open. Record the destination, matched rule, outbound group, and final node for each test.

On Windows, TUN setup commonly requires an administrator-approved service or permission to create and configure a virtual network adapter. Approve only the service or elevation requested by the client you trust. On macOS, allow the network extension or VPN configuration when the operating system asks, then verify that it remains active after reconnecting. On Linux, route and interface setup may require elevated privileges or appropriate network capabilities; a client running in a restricted desktop session or container may not be able to install routes.

Menu labels change between client releases. Look for settings such as “TUN Mode,” “Service Mode,” “Run as administrator,” or “Install service,” and read the client’s own status indicator. A checked TUN toggle is not sufficient evidence by itself: confirm that the virtual interface is active and that a test connection appears in mihomo’s connection panel.

Enable TUN and Route Developer Domains

For a first test, enable TUN in the client interface and leave the rest of the profile unchanged. Many graphical clients manage the TUN interface and route installation themselves. If the client supplies a TUN override, prefer that supported interface to editing generated subscription files, which may be replaced during an update.

For a mihomo configuration you maintain directly, the following is an illustrative fragment, not a complete profile. Merge it into the active configuration only after checking the core’s supported fields. The Developer group must exist, and the example group name and DNS behavior should be adapted to your setup.

mixed-port: 7890
mode: rule
log-level: info

tun:
  enable: true
  stack: mixed
  auto-route: true
  strict-route: true
  dns-hijack:
    - any:53

rules:
  - DOMAIN-SUFFIX,github.com,Developer
  - DOMAIN-SUFFIX,githubusercontent.com,Developer
  - DOMAIN-SUFFIX,npmjs.org,Developer
  - DOMAIN-SUFFIX,pypi.org,Developer
  - DOMAIN-SUFFIX,pythonhosted.org,Developer
  - DOMAIN-SUFFIX,docker.io,Developer
  - DOMAIN-SUFFIX,docker.com,Developer
  - DOMAIN,auth.docker.io,Developer
  - MATCH,PROXY

The order of rules matters. mihomo evaluates rules from top to bottom and uses the first match. Put specific developer-domain rules before broader rules that could match those requests. MATCH,PROXY is only an example fallback; if your configuration uses a differently named group, replace it. Some organizations intentionally route internal registries or private code hosts directly, so do not send every domain through a proxy without checking access requirements and policy.

Domain rules work only when mihomo can associate a connection with a domain. DNS handling, cached addresses, applications that connect directly to IP addresses, and encrypted or application-specific name resolution can affect matching. If the connection panel shows an IP-based rule or the fallback rule instead of the expected domain rule, inspect DNS and the actual destination rather than repeatedly changing the selected node. The dns-hijack example is not a universal DNS prescription; confirm that the client and core support it and that it fits your existing DNS configuration.

TUN captures IP traffic and then mihomo applies routing rules; it does not transform SSH into HTTP. Git over HTTPS usually creates an HTTPS connection that can be routed by TUN. Git over SSH typically uses TCP port 22, so it needs a route that sends its destination through a suitable proxy group and a proxy transport that can carry that connection. Some networks block direct port 22. In that case, configure Git to use an approved SSH-over-HTTPS endpoint or switch the remote to HTTPS where appropriate; simply setting HTTPS_PROXY does not automatically proxy SSH.

Test Git, npm, pip, and Docker Separately

Once TUN is active, test one tool at a time. Start with a lightweight request and inspect the connection panel immediately afterward. A successful browser page does not prove that a package manager or daemon used the same route.

• Git: Check the remote with git remote -v to see whether it uses HTTPS or SSH. Try a read-only operation such as git ls-remote <repository-url>. If the operation fails, note whether the destination is the repository host, an authentication host, or an SSH endpoint. Do not paste access tokens or private repository URLs into public logs.
• npm: Run npm ping or request package metadata before installing dependencies. Check whether an npm-specific registry is configured with npm config get registry. A company mirror may need to remain direct or use a different route from the public registry.
• pip: Test with python -m pip index versions PACKAGE if the installed pip version supports it, or make a small request to the configured package index. Inspect pip config list for a custom index or proxy setting, and avoid exposing credentials embedded in configuration output.
• Docker: First test a small, public image that is appropriate for your environment. The daemon often performs pulls, not the terminal process that ran docker pull. A daemon launched as a service may not inherit the shell’s proxy variables, and Docker Desktop may route traffic through its own virtualized networking.

For tools that support explicit proxies, an environment-variable test can help distinguish an application setting from a TUN routing problem. In a POSIX shell, a temporary test might look like this:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7891

git ls-remote https://example.org/owner/project.git
npm ping

Replace the ports with the actual listeners in your active profile. The example assumes an HTTP proxy on port 7890 and a SOCKS listener on port 7891; a configuration with only mixed-port may expose HTTP and SOCKS on the same port, but check the client and core configuration rather than assuming. The socks5h scheme asks a compatible client to resolve the hostname through the proxy; support varies by tool. Environment variables are not a replacement for TUN and should be unset after a temporary comparison if you do not want them to affect later commands.

For Docker, configure the daemon or Docker Desktop’s proxy controls if the daemon itself needs an explicit proxy, following the documentation for your installed version. TUN on the host may capture some daemon traffic, but behavior depends on the host platform, Docker’s network mode, and how the daemon is isolated. Containers may have a different DNS resolver and route from the host. When a host-side test works but an in-container request fails, inspect container DNS, bridge networking, daemon logs, and the connection panel separately.

Troubleshoot TUN by Observing the Route

Change one variable at a time. After each test, compare the terminal result with the connection record in the Clash client. This avoids confusing a DNS failure, blocked destination port, missing route, and invalid proxy credentials as the same “terminal proxy” problem.

On Windows, check whether the client reports an active TUN adapter and whether Windows has a route associated with it. If enabling TUN breaks all network access, turn it off through the client interface and restore the previous network state before trying another configuration. On macOS, check that the network extension remains authorized and that no second VPN is replacing the default route. On Linux, inspect the active route table and interface state using the system’s normal network tools; do not copy route commands from another distribution without understanding their effect.

For a useful log, reproduce one failure and note the exact time, destination host, client status, and selected proxy group. Avoid uploading a full configuration or diagnostic bundle without reviewing it: subscription URLs, tokens, private hostnames, and internal IP addresses may be included. If TUN works only while the client is open, that may be expected because the client owns the virtual interface and routes. Do not assume that closing the window leaves the service running.

FAQ: Clash TUN for Developer Tools

Does TUN make Git, npm, and pip use the same route as a browser?

Not necessarily. TUN can capture their IP traffic when the operating system routes it through the virtual interface, but mihomo still applies rules to each destination. A browser and package manager may contact different domains, use different DNS behavior, or use different transports. Confirm the actual rule and outbound in the connection panel for each tool.

Should I keep proxy environment variables enabled with TUN?

Usually, test TUN alone first. Environment variables can be useful for tools that need an explicit proxy or for comparing behavior, but combining them with TUN may create confusing or duplicate proxy paths. If a tool needs explicit settings, configure only the variables or application options it supports and document how to clear them.

Why does Docker behave differently from a terminal command?

The Docker daemon commonly performs image pulls independently of the shell. Docker Desktop also uses virtualized networking, while Linux deployments may use a system service and bridge networks. Configure and test the daemon, host, and container as separate network contexts rather than assuming a successful host request proves that all three are covered.

Is TUN required to proxy terminal traffic?

No. A tool that supports HTTP or SOCKS proxy settings can often use an explicit proxy without TUN. TUN is useful when applications do not honor desktop proxy settings or when you want rule-based capture across more system traffic. Choose the least complex method that works for the tools and network you need.