Running mihomo on a Router or Bypass Gateway: Whole-Home Proxy Deployment

Why push the proxy down to the router layer

Desktop clients (Clash Verge Rev, FlClash, and the like) run the proxy on a single device — configuration is straightforward and the interface is friendly, but coverage stops at that one machine. Your TV box, smart speaker, tablet, printer, and a friend's borrowed phone all fall outside the proxy — they either hit the public internet directly or can't be configured for a proxy at all. Deploying the mihomo core straight on a router or bypass gateway effectively detaches "proxying" from individual endpoints and hangs it at the network egress instead: every device connected to that router automatically gets proxy capability, without repeating install-and-subscribe steps on each one.

This "whole-home proxy" approach fits a few scenarios especially well: a household with lots of mixed device types, a need to give an outbound path to smart devices that can't take a custom proxy config (TVs, set-top boxes), or simply wanting to avoid maintaining a client on every device. The cost is a much higher setup bar than installing a desktop client — you'll be touching config files, the command line, and need some basic networking knowledge. Troubleshooting also relies on logs rather than a client's visual connectivity indicators.

Hardware choice: flash the main router or use a bypass gateway

Before deploying, settle on one of two common hardware paths:

• Flash mihomo-capable firmware directly onto your main router: fits cases where you're already planning to replace your router and don't need rock-solid stability from it. Upside: one fewer device, simpler topology. Downside: the main router carries all forwarding load, and a firmware issue takes the whole house offline — risk is concentrated.
• Bypass gateway setup (recommended for most homes): attach a small device (a mini x86 box, Raspberry Pi, or a flashable secondhand router) behind your existing main router, running only mihomo, while the main router keeps handling DHCP and normal routing. Point the gateway address or default route at the bypass device. This topology requires minimal changes, doesn't touch main-router stability, and if something breaks you can just point the default route back at the main router to restore internet access — low rollback cost, and a better fit for anyone trying whole-home proxying for the first time.

On specs, mihomo itself doesn't demand much CPU or RAM — a dual-core device with 512MB+ of memory typically runs it stably on a gigabit connection. If your bandwidth exceeds 500Mbps and you're running a large rule set, budget more RAM and a somewhat stronger CPU to avoid forwarding bottlenecks as rule matching and connection counts climb. A few dozen to a hundred-odd MB of storage is plenty for the core and config files.

OS preparation

Different hardware paths mean different OS environments, but the workflow is consistent:

1. Confirm the system architecture: before downloading the mihomo core, check whether your device is amd64, arm64, or something else — a mismatched architecture means the binary simply won't run.
2. Prepare the runtime environment: on a Linux-based bypass gateway (a standard distro or OpenWrt-family firmware), make sure basic networking tools (iproute2, iptables or nftables) and boot-script support are present. If your router firmware supports third-party plugins, check first whether a ready-made mihomo/Clash plugin package already exists — it can save you manual compilation and dependency hunting.
3. Disable conflicting components: if the device previously ran another proxy or transparent-proxy setup, confirm the old forwarding rules and DNS hijack rules are cleared out first, so old and new rules don't stack and send traffic in confusing directions.
4. Keep a management path open: get SSH or the firmware's built-in admin console working before you deploy, so you can check core logs and restart services later — don't wait until the network drops to discover the management path itself got routed through the proxy rules and became unreachable.

Config file placement and key fields

The config file mihomo uses follows the same YAML structure as the Clash family of configs, with core fields covering inbound ports, mode, DNS section, and proxy rules — essentially the same thing that happens behind the scenes when a desktop client "imports a subscription," except at the router layer you place the file path manually and manage the service lifecycle yourself. A typical minimal skeleton looks roughly like this:

mixed-port: 7890
mode: rule
log-level: info
tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
dns:
  enable: true
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

In practice, the proxies and rules sections are usually replaced entirely by the remote config from your subscription link, so you won't be hand-writing every node's details. Once the subscription-generated config file lands in the core's expected config directory, the core reads it on startup and builds the proxy groups and rule table from it. Most deployments store the config file separately and point the core to that fixed path with a startup argument, so future subscription updates only require swapping the config file itself, with no need to touch the startup script.

Rule syntax matches the desktop client — the usual matching priority is domain rules, then IP rules, finally falling through to MATCH as a catch-all, e.g. direct connection for domains in mainland China, proxying for specific services, and policy-group splitting for the rest. Once the rule count grows, it's worth using rule providers to reference remote rule files instead of stuffing thousands of lines into the main config — easier to update and lighter on the core's startup parsing.

Transparent proxy modes: TUN vs. gateway hijacking

The core problem router-layer deployment has to solve is getting connected devices to hand traffic to mihomo transparently. There are two common approaches:

TUN mode taking over all egress traffic

Enabling TUN mode on the bypass gateway or flashed router makes the core create a virtual network interface and automatically take over the system routing table — all traffic forwarded through that device flows into mihomo first and gets split according to the rules. This is comparatively simple to configure, needs no extra iptables forwarding rules, and has better compatibility, making it the mainstream approach for router-layer deployment today. It corresponds to the tun.enable and auto-route fields in the sample above.

Gateway hijacking and DNS splitting

Have other devices on the LAN treat the machine running mihomo as their default gateway (or just point the default route to the bypass gateway), and each device's DNS requests and TCP/UDP traffic get funneled through it for centralized handling. This requires adjusting the default route or DHCP gateway address at the network level, which demands more networking knowledge — but the payoff is that connected devices need zero configuration; plug in a cable or join the Wi-Fi and they get proxy capability automatically. This is what "whole-home proxy" is ultimately aiming for.

The two approaches aren't mutually exclusive — most real-world deployments combine "TUN takeover of local forwarding traffic on the bypass gateway" with "LAN devices pointing their gateway at the bypass device," turning the bypass gateway into the LAN's unified egress point.

Autostart and ongoing stability

Routers and bypass gateways typically stay powered on long-term, and if the core can't come back up automatically after a power cycle, the whole house's network goes down with it — so autostart isn't optional, it's a requirement. On devices with a system service manager, the usual approach is to write the core's startup command as a service unit set to launch automatically at boot and restart itself after an unexpected exit. On routers running a plugin-based firmware ecosystem, the plugin itself typically already has autostart logic built in — just tick "start with router" in the admin UI.

• Check core logs periodically for rule-matching errors or node connection failures, so a "looks running but not actually working" state doesn't go unnoticed for a long time.
• Reload the config after a subscription update (most deployments support hot reload without restarting the whole service), cutting the brief downtime that comes with config changes.
• Keep a direct-connection or whitelist rule for the management path, so a rule update can't accidentally lock you out of your own admin console.
• Keep an eye on core version updates — mihomo iterates fairly quickly, and new versions usually bring protocol compatibility fixes and performance improvements. Check the release notes before upgrading to avoid config field changes causing a startup failure.

Weighing this against a desktop client

Router-layer deployment and desktop clients aren't an either-or choice — they fit better combined based on what you need:

• Coverage: router-layer deployment covers every device in the house at once; a desktop client only covers the one machine it's installed on. If you have lots of smart devices or frequent guests joining your network, router-layer deployment has lower marginal cost.
• Visibility and ease of use: desktop clients offer a graphical interface, connectivity tests, and node latency at a glance, making self-diagnosis easy. Router-layer setups lack all of that — troubleshooting relies on logs and the command line, which isn't friendly for non-technical users.
• Flexible switching: a desktop client can switch proxy policy per app or per window at any time; router-layer policy applies uniformly across the whole network, and getting per-device differentiation requires extra policy-routing knowledge.
• Blast radius of failure: if a desktop client breaks, only that device is affected; if router-layer deployment breaks — especially when the main router itself was flashed — the whole house can lose internet, which is exactly why the bypass gateway approach was recommended earlier.

A common combination is using router-layer deployment to give basic proxy capability to devices that are awkward to install a client on — TV boxes, smart devices — while continuing to use desktop or mobile clients on your own computer and phone for finer-grained per-app splitting. The two complement each other rather than replacing one another.