Preface
Clash Meta, now commonly distributed through Mihomo-based clients, can route traffic in several ways. The simplest option is the ordinary system proxy, where applications voluntarily use an HTTP or SOCKS5 endpoint. That approach is convenient, but it does not cover every Linux application. Command-line tools, sandboxed desktop apps, containers, game launchers, DNS utilities, and software with its own networking stack may ignore the desktop proxy completely.
TUN mode solves this coverage problem by creating a virtual network interface. Instead of waiting for each application to understand proxy settings, the Linux kernel sends IP traffic through the interface and Clash applies its routing rules at a lower level. This makes the setup useful for desktop systems, development machines, and headless hosts where consistent routing matters.
This guide explains a practical Linux setup from the ground up. It covers the kernel prerequisites, a safe YAML baseline, permissions, DNS behavior, service startup, verification commands, and the conflicts that most often prevent the interface from working. The examples are written for a Mihomo-compatible Clash Meta core and can be adapted to a graphical client such as Clash Verge Rev.
What You Will Achieve
A working Linux TUN interface that captures application traffic, resolves DNS through Clash, and starts reliably without creating a permanent routing loop.
1Check the Linux Prerequisites
Before editing the profile, confirm that your distribution and kernel can create a TUN device. Most current Ubuntu, Debian, Fedora, Arch, and openSUSE installations include the required support, but minimal cloud images and hardened systems may omit the module or device node. Checking first is faster than debugging an apparently incorrect YAML file.
Core and Client Requirements
You need a Clash Meta or Mihomo core that supports the tun: configuration block. An older binary may start successfully while silently ignoring newer options, so check its version before proceeding. You also need a valid profile containing at least one proxy, a proxy group, and rules. TUN mode is only the traffic capture layer; it does not provide servers or subscriptions by itself.
If /dev/net/tun does not exist, load the kernel module and check again:
On a normal system, the device should be present with read and write permissions. If your distribution does not create it automatically, you can create the device node manually, although persistent device management should normally be handled by udev:
Permissions and Network Capabilities
Creating a TUN interface and modifying routes require capabilities that an ordinary desktop process may not have. The straightforward first test is to run the core with sudo. Once the configuration is proven, you can use a system service with restricted capabilities instead of giving a graphical application unrestricted root access.
- Use an administrator account for the first launch and for installing a system service.
- Keep the profile and secret subscription URL readable only by the account that needs them.
- Do not copy a subscription URL into public issue reports or shell history.
- Record the original default route before enabling TUN mode so that a failed setup can be reversed safely.
Do Not Skip the Baseline
Run ip route and note your default gateway before testing. A routing loop can make the machine appear offline, especially when the proxy server is reached through the same interface that Clash is trying to capture.
2Build a Safe TUN YAML Configuration
The exact profile structure depends on your provider, but the TUN and DNS sections are portable across most Mihomo-compatible configurations. Add them at the top level of the YAML file, aligned with mixed-port, dns, and rules. YAML indentation is significant: use spaces rather than tabs and keep child properties consistently indented.
The TUN Block
The following baseline enables the virtual interface, uses the system stack, and asks Clash to manage routes. auto-route inserts the routes required to capture traffic, while auto-detect-interface helps the core select the active physical interface on laptops that move between Wi-Fi and Ethernet.
system is usually the best first choice on Linux because it integrates with the kernel networking stack and avoids the extra memory overhead of userspace packet processing. Some environments may work better with gvisor, but changing the stack should be a troubleshooting step, not the first adjustment.
DNS Configuration
TUN mode can capture IP traffic while DNS still escapes through the local resolver if the DNS section is incomplete. That creates confusing symptoms: websites may open by IP, but domain-based rules behave incorrectly or services may detect a different network location. A practical configuration uses fake-IP mode and encrypted upstream resolvers.
Choose the fallback policy that matches your routing goals. The example is intentionally generic; users who need local services to resolve locally may add a separate nameserver policy for private domains. Do not blindly copy public resolver addresses into an enterprise environment where internal DNS names are required.
Routing Rules and the Final Policy
The final rule decides what happens when no specific match exists. A common mistake is to enable TUN mode but leave the final policy as DIRECT, then conclude that the interface is broken because traffic never uses a proxy. Another mistake is sending local network traffic through a remote node, which can break printers, NAS devices, and router administration pages.
Replace Proxy with the actual name of your policy group. Keep private networks direct unless your environment specifically requires them to be tunneled. If you use a subscription profile that regenerates the entire YAML file, place local overrides in the client’s dedicated override area rather than editing a generated file that will be replaced during the next update.
3Install and Start Clash Meta
There are two common Linux workflows. A graphical client provides profile management and a convenient toggle for TUN mode, while a standalone Mihomo binary offers a smaller footprint and is better suited to servers. Both ultimately use the same core concepts: a configuration path, a controller or log output, and sufficient network permissions.
- Install a current Mihomo-compatible client from the Clash Download Page.
- Import your subscription or local YAML profile and wait until the proxy groups populate.
- Open the client settings, enable TUN Mode, and select the system stack if a stack selector is available.
- Allow the client to request administrator authentication when it needs to create the interface or modify routes.
- Check the client log for a message indicating that the TUN device was created successfully.
Use a Separate Test Profile
Create a minimal profile for testing before changing a complex daily-use subscription. This makes YAML errors, bad rules, and DNS problems much easier to isolate.
Place the binary in a protected directory and keep the configuration in a dedicated directory:
The -d option tells the core where to find its configuration and working files. Use the foreground launch during the first test because errors remain visible in the terminal. Once the profile works, move it into a systemd unit for automatic startup.
Check the Logs Before Repeating Commands
Messages such as “address already in use,” “operation not permitted,” and “route exists” indicate different problems. Save the first error and diagnose that specific layer instead of repeatedly restarting the core.
4Configure DNS and Avoid Routing Loops
DNS and routing are closely connected in TUN mode. When Clash resolves the proxy server hostname through its own tunnel before the tunnel exists, startup can fail. When DNS queries are sent through the wrong interface, the browser may display a connection error even though the TUN device appears in ip link.
Protect the Proxy Server Path
The proxy server itself must remain reachable through the physical interface. Mihomo generally handles this automatically, but complex rule sets, policy routing, or an existing VPN can defeat automatic detection. If you know the proxy server’s IP address, add an explicit direct rule or route for it. Never send the endpoint used to build the tunnel back through the tunnel.
The address above is documentation space and must be replaced with the real endpoint address when appropriate. If the provider uses several rotating addresses, a fixed rule may become stale. In that case, rely on the core’s automatic exclusion behavior and verify the result with logs and route inspection.
System Resolver Integration
Linux distributions manage DNS in different ways. Ubuntu may use systemd-resolved, while other systems use NetworkManager, resolvconf, dnsmasq, or a manually maintained /etc/resolv.conf. Do not assume that changing the file directly is permanent. A network manager may overwrite it seconds later.
- Check the active resolver with
resolvectl statuswhen systemd-resolved is installed. - Check which process owns DNS port 53 with
sudo ss -lntup | grep ':53'. - Use Clash’s DNS hijacking only when no other local service must own the same listener.
- Keep a local resolver available for private domains if your workplace or home network depends on them.
If port 53 is already occupied, leave Clash’s DNS listener on a separate port such as 1053 and configure the client or resolver integration to forward queries there. Forcing two services to bind the same address usually causes a startup failure rather than a useful fallback.
5Verify the TUN Interface and Traffic
Successful startup is not proof that traffic is being captured. Test the interface, route table, DNS path, and actual application behavior separately. A layered test prevents you from changing several settings at once and losing track of which change solved the problem.
Interface and Route Checks
The interface name may differ if your client chooses another device name. Look for a virtual interface with an assigned address and an active state. The route table should show rules or routes associated with the TUN device, but the exact output varies by core version and whether strict routing is enabled.
DNS and HTTP Tests
The first command tests the system resolver, the second tests ordinary application routing, and the third tests the local SOCKS endpoint directly. If the direct SOCKS request works but the ordinary HTTPS request fails, focus on TUN capture, routes, or DNS hijacking. If both fail, inspect the proxy group, subscription, node health, and core logs first.
Check for Leaks and Local Access
Visit an IP-checking service only after confirming that the test is appropriate for your privacy requirements. Compare the reported public address with the selected Clash node and check whether IPv6 is unexpectedly visible. Also test local resources such as your router dashboard, printer, and file server. A correct configuration should preserve the local destinations you intentionally marked as DIRECT.
Healthy Result
The TUN interface remains up, ordinary applications follow Clash rules, DNS responses match the selected policy, and the proxy endpoint remains reachable without a reconnect loop.
6Automate Startup with systemd
Manual startup is useful during development, but a workstation or server should recover after reboot without requiring an open terminal. A systemd unit also provides consistent permissions and logs. Create the service only after the profile has worked successfully in the foreground.
Use a unit similar to the following. Adjust the user, group, binary path, and configuration directory to match your installation:
Then reload systemd, enable the service, and inspect its status:
Running the service as root is easy to understand but grants more access than the core may need. Advanced users can create a dedicated service account and grant only the capabilities required for TUN and routing. Make that change after the configuration is stable, because permission errors are easier to interpret in a controlled migration than during the initial setup.
7Troubleshoot Common Linux Conflicts
“Operation Not Permitted”
This usually means the process cannot open /dev/net/tun, create a link, or modify the routing table. Confirm the device exists, test with administrator privileges, and inspect the service capabilities. Containers add another layer: the container may need access to /dev/net/tun and the host may need network administration capabilities. Do not grant broad privileges permanently without understanding the security impact.
The TUN Device Already Exists
A previous crash or a second networking tool may have left the device behind. List interfaces with ip link and identify which process owns the related service. Stop duplicate Clash instances, WireGuard, OpenVPN, NetworkManager profiles, or another transparent proxy before removing anything. Removing an interface that belongs to another VPN can disconnect unrelated users.
DNS Port or Resolution Conflict
A local dnsmasq, systemd-resolved, or VPN resolver may already occupy port 53. The symptom is often a startup error followed by browsers reporting that DNS cannot be found. Identify the listener, choose a non-conflicting Clash DNS port, and decide which service should be authoritative. Avoid running multiple automatic DNS managers unless you intentionally understand their forwarding order.
Existing VPN and Policy Routing
WireGuard and OpenVPN can install their own default routes and firewall marks. When both tools try to be the full-tunnel gateway, packets may bounce between interfaces or disappear into a policy table. Test with one transparent networking tool at a time. If simultaneous use is required, define explicit route priorities and exclusions for the proxy endpoint, LAN ranges, and VPN subnets.
Slow or Unstable Performance
Start by checking whether the issue exists in ordinary system proxy mode. If it does, TUN is not the root cause; test the selected node, MTU, upstream congestion, and DNS latency. If only TUN mode is slow, compare the system and gvisor stacks, temporarily disable strict route, and inspect CPU usage. A very small MTU on a VPN underneath Clash can cause fragmentation and retransmissions, so measure before lowering values randomly.
Change One Variable at a Time
Keep a short record of every configuration change and its result. TUN problems often involve DNS, routes, permissions, and another VPN simultaneously; changing all four at once makes the final setup difficult to maintain.
Best Practices for a Reliable Linux Setup
Linux offers more control than many desktop platforms, but that flexibility also exposes more networking layers. A basic system proxy is often enough for browsers and standard desktop applications. TUN mode becomes valuable when you need consistent capture for programs that ignore proxy variables, when you want one rule system for the entire workstation, or when you are operating a headless machine without a desktop proxy manager.
Compared with a traditional all-or-nothing VPN, Clash Meta gives you finer control over destinations. You can keep private networks direct, route selected services through a named policy group, choose different DNS behavior for different domains, and change nodes without rebuilding the entire network tunnel. Compared with manually maintained iptables or nftables rules, Clash provides a more approachable configuration model and visible policy groups while still using the Linux routing stack underneath.
- Keep the core and client updated so that TUN, DNS, and kernel compatibility fixes are available.
- Use a dedicated test profile before applying changes to a large subscription configuration.
- Exclude LAN ranges and the proxy endpoint deliberately rather than assuming every network should be tunneled.
- Check DNS ownership and existing VPN routes before enabling automatic routing.
- Use systemd for repeatable startup and retain logs for diagnosing future updates.
- Protect subscription URLs, controller ports, and configuration files from other local users.
Clash Meta is particularly useful on Linux because its rule engine, DNS handling, and TUN support can be adjusted independently. Once the interface, resolver, and route table have been verified, the setup becomes predictable: applications send traffic to the kernel, Clash evaluates the rules, and the selected policy determines whether the packet is direct or proxied. Start conservatively, test each layer, and expand the configuration only after the baseline is stable.