What this guide covers (and how it differs from Ubuntu)

Debian 12 (bookworm) is close enough to Ubuntu that many Clash Meta tutorials almost work—until they do not. The failure modes are rarely exotic; they are usually permission, resolver, or routing assumptions that Ubuntu’s defaults paper over. This article is written for people who already understand Mihomo basics and want a coherent Debian path: verify the kernel path for TUN mode, place files where an administrator can reason about them, start the core under systemd with the right capability bits, then align DNS so capture mode does not fight the OS.

We will not rank upstreams or nodes. We will not duplicate the entire YAML reference. Instead, you get an installation story that complements the distribution-specific guides already on this site—pair it with the Ubuntu Clash Meta walkthrough if you want a direct side-by-side, or the Fedora Workstation edition if you are comparing RPM versus apt ergonomics. For capture-mode concepts before you edit tun: blocks, read the Clash TUN mode guide here first; the mental model is the same on Linux, only the resolver plumbing changes.

Step 1: Bookworm baseline—packages, TUN, and quick sanity checks

On a minimal Debian VPS you might not even have curl or a sensible CA bundle yet. On a desktop spin you might have NetworkManager and systemd-resolved behaving like a modern Ubuntu install. Treat both as valid targets, but do not assume packages are identical to “whatever worked on Jammy.”

Install a small toolchain you will need for any serious debugging session:

sudo apt update
sudo apt install -y ca-certificates curl dnsutils iproute2 procps

If you plan to compile auxiliary tools, add build dependencies later; most users run a published Clash Meta binary for Linux amd64 or arm64. Confirm architecture with uname -m before you download the wrong archive—mixed arm64 cloud instances are common now, and a silent “Exec format error” in journalctl wastes an evening.

TUN is not a Debian package; it is a kernel interface. Verify the module and device node before you blame YAML:

sudo modprobe tun
ls -l /dev/net/tun

You should see a character device. If modprobe fails, you are on a custom kernel or a container without tun support—fix that layer first, because no amount of auto-route: true helps. On full VMs and bare metal, bookworm’s default kernel almost always exposes TUN unless the host stripped it.

Debian 12’s firewall story trends toward nftables even when you type iptables—many images install a compatibility shim. That matters because capture mode eventually manipulates policy routing and sometimes expects netfilter cooperation. Keep notes on whether you run ufw, raw nft, or provider-specific scripts; mixing “manual rules I forgot about” with Mihomo’s auto-route is a classic source of intermittent drops.

Step 2: Directory layout, ownership, and where the binary lives

Pick a boring layout and keep it. A pattern that audits well on servers:

  • /usr/local/bin/mihomo (or clash-meta)—the executable, root-owned and not world-writable.
  • /etc/mihomo/config.yaml—configuration referenced by your unit file; tighten permissions if it contains secrets.
  • /var/lib/mihomo—writable state: caches, downloaded rule providers, GeoIP files.

Create a service account mihomo if you want isolation. On a single-user laptop, running as your own UID is acceptable if you understand that any process running as you can poke the same files. Never leave the state directory world-writable.

Fetch builds from the official Clash download page rather than random mirrors. Before you involve systemd, run interactively once:

sudo -u mihomo /usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml

If YAML parsing fails, fix it here while stdout is immediate. Jumping straight to journalctl turns every typo into a faux “Debian networking bug.” When the interactive run shows listeners, you are ready to automate.

Step 3: Minimal YAML health before you enable TUN

Most “TUN broke Debian” threads are DNS loops or mixed resolver strategies that only surface once auto-route pushes traffic into Mihomo. Start with a profile that already works in listener-only mode: a mixed port on 127.0.0.1, a conservative external-controller bind, and DNS settings that do not wrestle port 53 away from the OS unless you intend to.

Checklist before tun.enable: true:

  • Listeners match what you test with (curl --proxy or browser extensions).
  • DNS mode and fake-ip choices are intentional, not copied from a phone profile.
  • You know whether Debian’s stub resolver (127.0.0.53) is in play—common on desktop installs with systemd-resolved.

If you are migrating profiles from another distro, walk the field renames in the Clash Meta upgrade guide so deprecated keys do not interact badly with newer TUN defaults.

Step 4: systemd autostart with capabilities (not root)

Debian uses systemd everywhere you care about. Mirror the working interactive command inside a unit such as /etc/systemd/system/mihomo.service. The critical difference between a toy unit and a reliable one is explicit identity, working directory permissions, restart policy, and capability sets for TUN mode.

Example skeleton—adjust names and paths to match your machine:

[Unit]
Description=Mihomo (Clash Meta) on Debian
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=3
AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
NoNewPrivileges=true
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Reload and enable:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl status mihomo.service --no-pager

If the service exits immediately, read journalctl -u mihomo -e. Typical Debian-specific surprises include AppArmor profiles on custom binaries, wrong architecture binaries, and SELinux contexts if you imported disks from a RHEL-family install—rare on stock bookworm, worth mentioning because homelab migrations happen.

Some administrators prefer setcap on the executable instead of ambient capabilities; both patterns appear in production. Avoid running the daemon as root indefinitely just to dodge capability configuration—you trade a few minutes of setup for a permanent blast radius expansion.

Step 5: Enable TUN stack, auto-route, and strict-route cautiously

When listeners are not enough—containers, static binaries that ignore environment proxies, games—TUN mode pushes policy to the IP layer. On Debian, start with the stack that maps to the kernel path you already trust:

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  strict-route: false

Enable one knob at a time. Confirm ip link shows a tunnel interface after restart, then validate default routes with ip route. Only then tune DNS hijacking or strict routing. If you flip five booleans at once and lose SSH, you will not know which assumption broke.

CAP_NET_ADMIN is mandatory for managing the tunnel; CAP_NET_BIND_SERVICE matters if you bind privileged ports. Those capabilities are why the unit file in the previous section differs from a generic “run my binary” snippet.

Step 6: DNS on Debian 12—resolved, resolv.conf, and leak tests

Debian desktops often stack NetworkManager on top of systemd-resolved, which listens on 127.0.0.53 and forwards according to link metadata. Minimal servers may use plain /etc/resolv.conf pointing at your provider. Mihomo may want to become the resolver for captured traffic; the failure you are avoiding is split-brain resolution where packets and queries disagree.

Practical guidance:

  • Decide who owns upstream DNS for captured clients—Mihomo or the OS—and draw it on paper if needed.
  • After enabling TUN DNS features, test both a public hostname and a LAN hostname that must stay on split routing.
  • When symptoms look like “sites load but stall,” inspect MTU black holes and resolver timeouts before rewriting policy groups.

If you need a broader troubleshooting map for fake-ip interplay, reuse the scenarios in the TUN guide; Debian differs from Windows mainly in how stubs are wired, not in the requirement that DNS and routing agree.

Step 7: Firewall notes—nftables, ufw, and provider scripts

Before you integrate Mihomo with host firewalls, answer one question: who installs the default FORWARD and nat rules today? On cloud images, cloud-init or a vendor agent may restore rules on reboot. On laptops, ufw might be enabled with defaults that assume a single uplink.

Work slowly: validate Mihomo without extra firewall layers, snapshot your nft list ruleset (or iptables-save), then add integration. If you skip this order, you will debug three systems at once—YAML, netfilter, and upstream congestion—and ship the wrong fix.

Step 8: Verification checklist (before you call it “done”)

  1. systemctl is-active mihomo reports active; logs show steady listener lines.
  2. ss -lntp lists your mixed or HTTP/SOCKS ports on the expected addresses.
  3. With TUN on, ip link and ip route show sane tunnel attachment without duplicate conflicting defaults.
  4. DNS answers for a canary name match the path you expect (direct versus policy).
  5. A controlled download or TLS probe changes behavior when you switch policy groups—proof the rule engine is in the path you think it is.

Only after those pass should you tune aggressive firewall hardening or cloud security groups. Otherwise you misattribute packet loss to Mihomo when the culprit is a half-written nft chain.

Symptom → likely cause → what to try (install errors, leaks, drops)

Use this table like a flight checklist when you migrate from Ubuntu or Fedora recipes and something feels “almost right.”

  • Binary refuses to start, “permission denied” on /dev/net/tun: missing CAP_NET_ADMIN, wrong user, or container without /dev/net/tun. Fix capabilities or the runtime environment before YAML.
  • modprobe tun fails: host kernel lacks TUN; some LXC templates need lxc.cgroup2.devices.allow or equivalent. No userspace workaround replaces the module.
  • Service runs, browser works, curl leaks: shell lacks proxy exports; TUN not capturing that traffic class; or a split DNS path. Test the same host with and without explicit --proxy, and compare routes.
  • Everything connects, then drops every few minutes: two clients fighting default routes (WireGuard plus Mihomo), DHCP renewals undoing policy, or flaky MTU on PPPoE-style links. Capture ip route before and after failure.
  • “Connected” but pages half load: classic DNS loop or poisoned path MTU; isolate with dig, mtr, and Mihomo debug logs before touching provider rules.
  • AppArmor denial lines in dmesg: confined profile blocks the relocated binary; adjust or relocate per Debian security docs—do not disable profiles globally without cause.

If your symptoms sound closer to “logs show silent DIRECT” than “kernel says no,” also read connected-but-no-internet DNS debugging on this site; the log-first mindset transfers cleanly to Debian.

How this fits next to other Linux guides

This Debian article deliberately sits beside—not on top of—the Ubuntu, Fedora, and Arch AUR pieces. Ubuntu readers get GNOME and systemd-resolved examples tuned to LTS cadence; Fedora readers inherit SELinux conversations; Arch readers start from packaging helpers. Debian 12 users often choose the distribution precisely for stability and predictable apt behavior—reward that choice with equally predictable file locations, capability-aware units, and resolver diagrams you can maintain months later.

When policy questions outgrow installation mechanics, continue in the Clash documentation hub for rule ordering, provider refresh intervals, and performance habits that matter more than any single sysctl tweak.

Closing: a stable Mihomo stack on bookworm

Debian 12 does not need exotic tricks to run Clash Meta well; it needs correct prerequisites, an honest accounting of DNS, and a systemd unit that grants the kernel permissions TUN mode expects. Lay down listeners, prove YAML health, add capture mode when it buys more than complexity, then verify routes and resolvers with simple tools. Compared with one-off proxy exports per application, a maintained Mihomo core with transparent upgrade paths and clear documentation usually wins on stability—especially on servers you SSH into at midnight.

If you want curated installers and room to grow into advanced routing without chasing nightly artifacts, align your Debian layout with the checklist above, then validate with two tests: one destination that must stay direct and one that must show policy egress. When both behave, you can trust autostart again.

→ Download Clash for free and experience the difference

Download Clash from this site