Run mihomo Directly on a Router or Bypass Router: Architecture Choices and Configuration Guide

Define the deployment goal first: what should mihomo do on the router?

When Clash runs as a desktop client on Windows, macOS, or a phone, the proxy usually covers only that device. Moving the mihomo core to a router or bypass router shifts the traffic entry point to the LAN gateway, allowing TVs, game consoles, smart speakers, and devices that cannot easily run a client to use rule-based routing. mihomo is the core continued from Clash Meta. It reads Clash-style YAML configurations and provides rule matching, proxy groups, DNS, TProxy, redirection, and TUN support.

The key challenge in a router deployment is not simply getting the core to run. Packets must actually pass through it and return along the correct path. A complete flow has at least four parts: LAN devices send traffic to the gateway, routing rules direct selected traffic to mihomo, the core chooses a direct or proxy exit according to the rules, and return traffic follows the right path back to the original device. Starting the process without transparent proxy rules does not make LAN devices use it automatically.

The core difference between a main router and a bypass router

The main-router path is the clearest: a LAN client’s default gateway is the device running mihomo, and the firewall only needs to identify traffic that should enter the transparent proxy port. A bypass-router setup must answer one additional question: why will clients send packets to the bypass router? Common options are setting the bypass router as the default gateway for selected devices or having the main router apply policy routing based on source addresses. Pointing client DNS at the bypass router alone does not automatically send ordinary TCP or UDP traffic through it.

Choosing firmware, architecture, and hardware resources

mihomo provides executables for different CPU architectures. Before deployment, run uname -m to confirm the system architecture rather than relying on the router’s product name. Common results include aarch64, armv7l, x86_64, and mips. The downloaded file must match the system architecture. For example, 64-bit ARM firmware normally uses an ARM64 build, while a device running 32-bit firmware cannot run an ARM64 file directly even if its CPU supports 64-bit operation.

Essential firmware capabilities

• The Linux kernel supports policy routing, with ip rule and ip route available on the system.
• The firewall provides nftables or iptables and supports the TProxy modules required for transparent proxying.
• The filesystem provides a persistent location for configuration, rule sets, GeoIP, and GeoSite data.
• The system can register a service at boot, such as OpenWrt’s procd or systemd on standard Linux.
• The system clock and DNS work correctly; otherwise subscription updates, TLS connections, and domain rules may fail.

Common OpenWrt 23.05 and later builds use firewall4 and nftables. Do not mix iptables commands from older guides without checking compatibility. Before deployment, open LuCI → “System” → “Software” and verify that components related to TProxy, nftables, and policy routing are available. You can also run nft list ruleset over SSH to identify the active firewall stack. If the command is missing, install the required firmware components instead of repeatedly editing the mihomo configuration.

Practical memory, storage, and CPU requirements

The core itself is only part of the overhead. Rule count, GeoSite data, DNS cache, connection count, and dashboard resources also consume memory. A 128 MB device can run a trimmed configuration, but leaves little headroom when loading large rule sets, enabling fake-ip, or handling many concurrent connections. 256 MB is a more practical starting point, while 512 MB or more makes it easier to run ad blocking, DNS services, and monitoring components together.

The figures below come from a LAN test on a six-core RK3399 ARM64 device with 4 GB of memory, OpenWrt 23.05.5, and mihomo v1.19.10. The test connection was 300 Mbps, with the downstream client connected over gigabit Ethernet and a configuration containing about 86,000 domain and IP rules. These results indicate approximate scale only and may not be reproducible with different encryption methods, node distances, or firmware builds.

A 100 Mbps connection and a few clients do not demand much CPU, but gigabit access, WireGuard, complex encryption, and heavy UDP traffic can raise the load substantially. On x86 or ARM soft routers, also check whether network ports share a bus and whether a USB network adapter is the bottleneck. CPU clock speed alone does not determine throughput; AES instructions, kernel drivers, and cooling also affect sustained performance.

Transparent proxy methods: TProxy, redirection, and TUN

The common interception methods on routers are REDIRECT, TProxy, and TUN. REDIRECT mainly handles TCP and is relatively simple, but it does not fully cover UDP and changes how the core sees the original destination. TProxy can transparently intercept both TCP and UDP while preserving the original destination information, making it a common choice for Linux router deployments. TUN receives IP traffic through a virtual network interface. Its configuration is conceptually straightforward, but on lower-powered routers it usually adds more context-switching and protocol-stack overhead.

TProxy ports and policy routing

mihomo’s tproxy-port only listens for transparent proxy traffic. The firewall must also mark selected packets, after which policy routing sends marked traffic to the local loopback interface. 7893 is a common listening port, but no specific port number is required; the configuration, nftables rules, and service permissions simply need to agree.

mixed-port: 7890
tproxy-port: 7893
allow-lan: true
bind-address: "*"
mode: rule
log-level: info

external-controller: 127.0.0.1:9090
secret: "Set a separate control secret"

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

mixed-port: 7890 is useful for temporary manual HTTP or SOCKS proxy tests from the LAN. If other devices really need access, restrict the source subnet with firewall rules. Keep the control interface listening on 127.0.0.1:9090 where possible. For a remote dashboard, use a controlled reverse proxy or SSH forwarding instead of exposing it directly to the WAN.

When to consider TUN

Consider TUN if the firmware lacks complete TProxy support or you want to reduce the amount of manually written policy routing. mihomo’s TUN configuration usually requires automatic routing and interface detection, but when the router also handles WAN, LAN, dialing, and bridging, automatic detection may not select the intended egress. After deployment, check the default route, TUN routing table, and local subnets. In particular, avoid sending the router’s management address or upstream gateway into TUN.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  strict-route: true
  dns-hijack:
    - any:53
    - tcp://any:53

stack: mixed is a common starting point, but platform support can change with the core version. Before enabling dns-hijack, confirm that port 53 on the LAN is not already being intercepted by dnsmasq, AdGuard Home, and another redirection rule at the same time. In practice, dnsmasq can continue listening on LAN port 53 while selected queries are forwarded to mihomo at 127.0.0.1:1053, leaving DHCP domain names and local hostnames under dnsmasq’s control.

Main-router deployment: keep failures within the service layer

With a main-router deployment, all clients already pass through the device, so you do not need to change the gateway on every endpoint. A safer rollout is to run mihomo first as a regular mixed proxy and confirm that 127.0.0.1:7890 works; then add transparent proxy rules for one test device; only after that expand the rules to the entire LAN. Even if the YAML or rules are wrong, the router’s basic NAT and DHCP can continue working.

1. Keep a directly connected management path for the router, such as a wired management port or a management device that bypasses transparent proxying.
2. Give the test client a fixed DHCP lease so rules can be added by source IP.
3. Intercept the client’s TCP traffic first, then verify UDP, DNS, and IPv6.
4. Confirm that direct sites, proxied sites, LAN device access, and the router admin panel all work normally.
5. Save a firewall configuration that can be rolled back, then expand the interception scope gradually.

IPv6 is a common blind spot. If LAN clients receive public IPv6 addresses while transparent proxying handles only IPv4, some applications may go directly over IPv6, making rules appear to fail randomly. The answer is not simply to disable all IPv6. Choose a clear approach: fully intercept IPv6, make relevant domains return IPv4 addresses, or disable IPv6 consistently at the RA and DHCPv6 layers until the network is ready. ipv6: true only allows IPv6 in mihomo’s DNS and connection capabilities; it does not create the required firewall rules automatically.

Rollback design for a main-router deployment

When the transparent proxy service stops, clients lose network access if the firewall still sends traffic to 7893. The startup script should launch the core and verify its listening port before loading transparent proxy rules; the stop script should remove the rules before terminating the process. On OpenWrt, procd can monitor the process and apply a restart policy, but avoid rapid unlimited restarts. Repeatedly launching a configuration with syntax errors wastes CPU and can flood the logs.

Bypass-router deployment: gateway, return path, and single-interface designs

A bypass router usually shares the same subnet as the main router. For example, the main router might be 192.168.10.1 and the bypass router 192.168.10.2. If a test computer uses 192.168.10.2 as its default gateway, the bypass router must enable IP forwarding and correctly send direct or proxied traffic to 192.168.10.1. The bypass router is then both the client gateway and the host running mihomo.

A single-interface bypass router has only one LAN interface, so inbound and outbound traffic share the same physical port. Wiring is simple, but the return path needs careful attention. If the main router sends replies directly to the client while requests pass through the bypass router, connection tracking may become asymmetric. A common solution is source NAT for traffic forwarded by the bypass router, or a static route on the main router pointing to the client subnet. The former is easier to configure but hides the client’s original address; the latter preserves address information but requires precise routing support on the main router.

Three ways to send clients through a bypass router

• Set the gateway manually: Change only one or two devices for testing. Point the client gateway to the bypass router; DNS can point to the bypass router or a designated LAN DNS server.
• Advertise the bypass-router gateway through DHCP: Suitable for migrating the whole network, but only one clearly designated DHCP service should assign addresses on the network to prevent clients from receiving conflicting gateways.
• Use policy routing on the main router: The main router sends traffic to the bypass router based on client IPs, MAC-bound leases, or subnets. This works well for staged rollouts but depends on the main router’s firmware capabilities.

The bypass router should not casually provide DHCP on the same broadcast domain while the main router does the same. If the bypass router must provide DHCP, disable DHCP on the corresponding main-router interface or place the two services in separate VLANs. During migration, keep one management computer using the main router as its gateway so both admin panels remain reachable if the bypass-router configuration fails.

Where to store configuration, subscriptions, and rule sets

mihomo should read its configuration from a persistent directory. On OpenWrt, /etc/mihomo/config.yaml is commonly used for the main configuration, /etc/mihomo/providers/ for proxy-provider files, and /var/lib/mihomo/ or mounted storage for runtime caches and large databases. Do not keep the only copy of the configuration in /tmp; on OpenWrt, /tmp is usually a memory filesystem and its contents disappear after a reboot.

/etc/mihomo/
├── config.yaml
├── providers/
│   ├── primary.yaml
│   └── backup.yaml
└── rules/
    ├── direct.yaml
    └── proxy.yaml

/var/lib/mihomo/
├── cache.db
├── country.mmdb
└── geosite.dat

Subscription URLs can be defined under proxy-providers and updated by mihomo at a set interval. Router flash storage has a limited write lifespan, so updates do not need to run too often. For most setups, start with interval: 21600, or 6 hours; rule sets can use 12- or 24-hour intervals depending on how often they change. Fetching every minute adds upstream requests as well as unnecessary writes and log entries.

proxy-providers:
  primary:
    type: http
    url: "https://example.invalid/subscription"
    path: ./providers/primary.yaml
    interval: 21600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

The domain above is only an example to show the configuration structure; replace it with the actual subscription URL before deployment. Configuration files usually contain access credentials, so restrict their permissions to the service user and administrators. After editing YAML, run the core’s configuration check before replacing the active file. Use spaces for indentation, and keep provider names, rule-set names, and outbound names referenced by policy groups exactly consistent.

Startup services, health checks, and log-based troubleshooting

Manual commands are useful for initial validation, but long-running services should be managed by a service supervisor. With procd on OpenWrt, the service script should define the executable, working directory, configuration directory, standard output, and restart policy. A standard Linux bypass router can use systemd and wait for the network with After=network-online.target. A successful service start does not prove that transparent proxying works; also check listening ports, firewall rules, policy routing, and DNS.

Recommended startup verification order

1. Run mihomo -t -d /etc/mihomo to verify that the configuration parses correctly.
2. After starting the service, use ss -lntup to confirm which of ports 7890, 7893, 9090, and 1053 are actually enabled.
3. Use ip rule and ip route show table all to inspect the policy-routing tables.
4. Use nft list ruleset to inspect traffic marks, private-range exemptions, and transparent proxy redirects.
5. From a test client, check domain access, direct IP access, a UDP application, and access to LAN devices separately.

Configuration errors usually report a field path and line number in the startup log. On OpenWrt, view them in LuCI under “Status” → “System Log”, or run logread -e mihomo. If the process exists but clients cannot get online, first confirm that the transparent proxy port is listening. If only domains fail, check the DNS upstream and port-53 path. If TCP works but games or voice calls fail, verify that UDP passes through TProxy. If the router admin panel is unreachable, check whether LAN private addresses were mistakenly intercepted.

Architecture decision: optimize for maintenance cost, not feature count

When the existing main router has enough CPU, memory, and maintainable firmware, and the home network is simple, running mihomo directly on it removes an extra layer and makes the default-gateway and transparent-proxy paths clearer. Keep a management entry point, enable the setup for one test IP first, and then expand it to the entire LAN.

A bypass router is a better fit when the main router is managed by the ISP, has limited firmware extensibility, or you want proxy failures isolated from basic internet access. Choose one clear design in advance: “clients use the bypass router as their gateway” or “the main router forwards selected traffic by policy.” Handle DHCP, return routes, and DNS beforehand rather than relying on multiple rule sets to connect by chance.

TProxy is better suited to a full-featured Linux routing environment and can cover both TCP and UDP. TUN fits devices with sufficient hardware resources that want all traffic handled through a virtual interface. Whichever method you choose, a stable deployment follows the same principles: persist the configuration, bypass proxy-node connections, start services and firewall rules in order, keep a rollback path, and verify each part with a single client.