Reading tip
Identify the scenario first, then follow the checks in order. Jump to the linked download, subscription or configuration page when the issue becomes specific.
Choose the Runtime Path
| Method | Best For | Watch For |
|---|---|---|
| systemd | General Linux servers | Config path and user permission |
| Docker | NAS and container management | Port mapping, network mode and TUN permission |
| GUI client | Linux desktop users | Use the matching client tutorial first |
Docker Compose Example
services:
mihomo:
image: metacubex/mihomo:latest
container_name: mihomo
restart: unless-stopped
network_mode: host
volumes:
- ./config.yaml:/root/.config/mihomo/config.yaml
- /dev/net/tun:/dev/net/tun
cap_add:
- NET_ADMINNAS permission models vary. Confirm whether the system lets containers access the virtual network adapter before using TUN.
Ports and Dashboard
- mixed-port handles local HTTP/SOCKS proxy traffic.
- external-controller is used by dashboards such as MetaCubeXD.
- Do not expose controller ports such as 9090 to the public internet without access control.
Using Logs
Do not rely only on dashboard state. Read startup logs to confirm the profile loaded, then inspect node connections, DNS queries and rule matches. Record each config change so it can be rolled back.