metacubexd

Mihomo Dashboard, The Official One, XD

✨ Features

• 📊 Real-time traffic monitoring and statistics
• 🔄 Proxy group management with latency testing
• 📡 Connection tracking and management
• 📋 Rule viewer with search functionality
• 📝 Live log streaming
• 🎨 Beautiful UI with light/dark theme support
• 📱 Fully responsive design for mobile devices
• 🌐 Multi-language support (English, 中文, Русский)

🖼️ Preview

Desktop Screenshots

Overview	Proxies

Connections	Rules

Logs	Config

Mobile Screenshots

Overview	Proxies	Connections

Rules	Logs	Config

🔗 Official Links

🚀 Deployment

metacubexd ships in three forms from one codebase:

The classic pure-panel mode still works against any remote mihomo — the kernel-control and profile features simply stay hidden when the dashboard isn't talking to a bundled agent.

1. Hosted Panel (point at your own mihomo)

Enable the external-controller in your mihomo config.yaml:

external-controller: 0.0.0.0:9090

Then either open the hosted dashboard and enter your mihomo {url, secret}:

…or self-host the static assets via external-ui:

# Clone the prebuilt gh-pages branch
git clone https://github.com/metacubex/metacubexd.git -b gh-pages /etc/mihomo/ui

# Set external-ui in your config:
#   external-ui: /etc/mihomo/ui

# Update to the latest build later:
git -C /etc/mihomo/ui pull -r

2. Desktop App

Download the installer for your platform from the latest release:

The desktop app bundles its own mihomo kernel and auto-configures the local endpoint — you don't enter any address. Manage profiles, edit configs, and start/stop the kernel directly inside the app.

These builds are unsigned. Each OS warns about unidentified developers; the steps below are expected and safe.

macOS — Gatekeeper blocks unsigned apps ("MetaCubeXD is damaged and can't be opened"). After dragging the app to /Applications, strip the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/MetaCubeXD.app

…or right-click the app → Open → Open in the confirmation dialog.

Windows — SmartScreen shows "Windows protected your PC". Click More info → Run anyway.

Linux — make the AppImage executable, then run it:

chmod +x MetaCubeXD-*-linux-*.AppImage
./MetaCubeXD-*-linux-*.AppImage
# or install the .deb:
sudo dpkg -i MetaCubeXD-*-linux-*.deb

System proxy / TUN are advanced features. The app defaults to a mixed proxy port (no elevation). System proxy and TUN both require privileges; see TUN mode (desktop) for the one-time privileged-helper install and what the unsigned build means for it.

TUN mode (desktop)

TUN takes over all machine traffic at the network layer, so every app is routed through mihomo without per-app proxy settings (unlike the mixed proxy port, which only catches apps you point at it). Because routing the whole system needs root/admin, the desktop app installs a small privileged helper the first time you enable TUN — a background service that performs the privileged network setup on the app's behalf. Enabling TUN therefore prompts for an administrator authorization the first time (the OS elevation dialog). The helper persists across sessions, so later enables don't re-prompt for install.

These builds are unsigned, so you hit the unidentified-developer warnings twice: once launching the app (see above — macOS Gatekeeper / Windows SmartScreen / Linux "unknown publisher"), and again when the helper install asks for administrator authorization. Both are expected. Allow them the same way you allowed the app itself.

Per-OS notes

• macOS — the helper is registered as a root LaunchDaemon; you approve it through the standard osascript "wants to make changes" administrator prompt. The kernel binds the system's utun interface.
• Windows — the helper is registered as an auto-start Windows service (UAC prompt). The build ships wintun.dll alongside the kernel, which mihomo's wintun backend needs — no separate download.
• Linux — the helper is registered as a root systemd unit; the elevation prompt is pkexec (the GNOME/PolicyKit authorization dialog). On a headless box without a Polkit agent you may need to install/enable one.

If TUN takes down your network

TUN reroutes default traffic, so a bad config or a stuck tunnel can drop connectivity. Two recoveries:

• Click "Recover network" in the app — it tears down the TUN routing and restores normal networking without quitting.
• Quit the app — exiting automatically tears down TUN (the helper restores routing), so a force-quit is a safe last resort.

Status: TUN is new. It's verified at the unit-test / command-generation / packaging level, but the real install, elevation, and per-OS tunnel behavior still need smoke testing on actual macOS / Windows / Linux machines. If you hit a problem, please open an issue with your OS, the exact prompt you saw, and whether "Recover network" restored connectivity.

3. All-in-One Server (Docker)

The metacubexd-server image bundles the dashboard UI, the control agent, and a per-arch mihomo kernel. One container serves the panel, supervises the kernel, and exposes the proxy.

# compose.yaml — proxy-only by default; TUN is an advanced override
services:
  metacubexd:
    image: ghcr.io/metacubex/metacubexd-server:latest
    restart: unless-stopped
    environment:
      CONTROL_TOKEN: 'change-me-control'
      CLASH_SECRET: 'change-me-clash'
      CONTROL_PORT: '8080'
      CLASH_API_PORT: '9090'
      MIXED_PORT: '7890'
      TZ: 'Asia/Shanghai'
    ports:
      - '8080:8080' # dashboard UI + /api/control agent API
      - '9090:9090' # mihomo Clash API + WebSocket (UI endpoint target)
      - '7890:7890' # mixed proxy port
    volumes:
      - 'metacubexd-data:/data'

volumes:
  metacubexd-data: {}

docker compose up -d

# Update
docker compose pull && docker compose up -d

Open http://<host>:8080 for the dashboard. The control agent unlocks the kernel/profile UI automatically: the server injects CONTROL_TOKEN into the same-origin page, so the dashboard authenticates its /api/control probe without you entering the token anywhere.

Point the UI endpoint at the kernel. The dashboard talks to mihomo's Clash API directly (never proxied), so set the endpoint to:

Environment variables

The named volume mounts /data, which holds your profiles, the active config, and the kernel's geo / fake-ip caches. It must be writable — a read-only data dir makes the kernel exit non-zero.

TUN mode (advanced)

TUN needs NET_ADMIN, the /dev/net/tun device, and host networking. Override the service:

services:
  metacubexd:
    image: ghcr.io/metacubex/metacubexd-server:latest
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    devices:
      - '/dev/net/tun:/dev/net/tun'
    environment:
      CONTROL_TOKEN: 'change-me-control'
      CLASH_SECRET: 'change-me-clash'
    volumes:
      - 'metacubexd-data:/data'

volumes:
  metacubexd-data: {}

With network_mode: host the ports: mapping is ignored — the container binds 8080/9090/7890 directly on the host. Enable a tun: block in your profile's mihomo config for the tunnel to come up.

Standalone panel image (Doc