Self-hosted service
MetaCubeX/metacubexd avatar
MetaCubeX/metacubexd

metacubexd and the mihomo controller it talks to

Mihomo Dashboard, The Official One, XD

4,697 stars557 forksTypeScriptMIT

At a glance

What is it?
metacubexd is a browser dashboard for a mihomo (Clash Meta) kernel you already run. What the panel adds is traffic charts, group switching and a connection table on top of an HTTP controller that you still have to expose and secure yourself.
Who is it for?
Adopt metacubexd if you already run mihomo on a machine you control and want a UI instead of editing config.yaml over SSH. Skip it if you were looking for a proxy client, because the panel container bundles no kernel and forwards no traffic of its own.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • MetaCubeX/metacubexd4,697 ★ · +296
Star history
Repository2026-09-232026-11-14
MetaCubeX/metacubexd4.4k4.7k

296 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Every panel screen is a request to the mihomo external controller

metacubexd forwards nothing and terminates no traffic. It is a browser front end for mihomo, the kernel also known as Clash Meta, and every chart, group selection and connection row it renders comes out of mihomo's HTTP external controller. The README's first step is to enable it and give it a secret in the mihomo config.yaml:

yaml
external-controller: 0.0.0.0:9090
secret: 'replace-with-a-strong-secret'

The panel then asks for a `{url, secret}` pair on its connect screen. Those two values are the entire trust relationship, which is why the README tells you to use a strong secret. Binding to 0.0.0.0 publishes that token on every interface the machine has, which is why the deployment notes tell you to put a firewall in front and to set external-controller-cors for the exact dashboard origin. The audience for this tool is narrow and specific: an operator of a router, NAS or VPS who already has mihomo running and wants read and switch access without SSH. It is not a client. Nothing on this page reaches the internet on its own.

One codebase ships as static files, an Electron app and a server image

The repository builds the same UI three ways, and the differences are not cosmetic. In hosted-panel mode the UI is a set of static files that you point a browser at from the official sites, from your own web server, or from a container that serves nothing but HTML over HTTP on port 80. The kernel is whatever remote mihomo you name. In desktop mode the app carries a bundled mihomo and supervises it. In all-in-one mode the Docker image carries the kernel, the UI and a small agent, and that bundle is the shape aimed at a router or a VPS.

That third form is why the panel sometimes looks broken when pointed at a plain mihomo. The kernel-control and profile features stay hidden in pure-panel mode, because the dashboard has no agent to ask. One panel can still manage several backends; which one the traffic view reflects depends on the endpoint you picked. Read the deployment table before assuming a missing control panel view is a bug: in the hosted-panel form it is the intended state.

external-ui turns a mihomo upgrade into a git pull

mihomo can serve a dashboard itself through its external-ui directory. The supported way to fill that directory is the prebuilt gh-pages branch, cloned straight into place:

shell
git clone https://github.com/metacubex/metacubexd.git -b gh-pages /etc/mihomo/ui

Afterwards, set external-ui to that path in config.yaml and mihomo serves the panel on the controller port. Upgrades are then a single command rather than a copy step, which matters on a router where every write is slow:

shell
git -C /etc/mihomo/ui pull -r

The trade-off sits in the branch name. You are tracking gh-pages, a build output, not main. Cloning it with -b and pulling it later keeps you on whatever the last CI run published.

DEFAULT_BACKEND_URL is baked into every served HTML response

The standalone container can pre-fill the connect form so a user does not have to type an address on first load. The entrypoint maps the variable into Nuxt runtime config, which means the value lands in the HTML the container serves on every request, with no image rebuild involved:

shell
docker run -d --name metacubexd -p 127.0.0.1:8080:80 \
  -e DEFAULT_BACKEND_URL=http://192.168.1.10:9090 \
  ghcr.io/metacubex/metacubexd:latest

Read the fine print before treating this as a lockdown. The value is only a default: the connect screen still lets a user edit it, and saved endpoints take precedence on later visits. Pre-filling skips the "no backend detected" prompt on first load; it does not lock the address. Anything that reaches the panel over HTTP can read whatever backend URL you configured, so treat that response as public inside your network.

The panel container serves HTTP on port 80 to dodge the browser mixed-content block

The quickest path to a running UI is a single container publish:

shell
docker run -d --name metacubexd -p 127.0.0.1:8080:80 ghcr.io/metacubex/metacubexd:latest

Open http://localhost:8080 and the connect screen appears. The image serves the dashboard over plain HTTP on port 80 and deliberately bundles no mihomo, so you point it at a kernel you run yourself. The README also spells out why the port is HTTP rather than HTTPS: a dashboard on https cannot script a controller on http, and the browser blocks the mixed content request before the panel ever sees it. The loopback binding limits the published port to the host under Docker’s default networking. Docker versions older than 28.0.0 can expose localhost-published ports to other hosts on the same network segment; verify your version and firewall settings.

That same constraint produces the most common failure. If you self-host the panel on a different origin from the mihomo controller, the connection can fail on CORS, not on the secret. The fix lives in mihomo, under external-controller-cors, matched to the dashboard origin exactly, and the failure message you get is a connection failure rather than an authentication one. Debug the cors policy before you start guessing at the token.

The build is a pnpm monorepo that emits a static Nuxt bundle

Development runs from the repository root as a workspace, with pnpm 10.34.1 pinned as the package manager and the root dev script delegating to the UI package. The production path is deliberately static: build:ui runs the UI generate step, then `generate` clears .output and copies packages/ui/.output to the repository root. That is the design decision behind the three distributions: one static output can be hosted by a CDN, by mihomo through external-ui, or by the desktop app, with no runtime differences for the reader to reason about.

The cost of that choice is that feature detection cannot be resolved at build time. Anything depending on whether a bundled agent is present has to be decided in the browser at runtime, which is why some views are simply hidden rather than disabled in the pure-panel form.

Commit shape decides the version number, so a tag can land without review

Version numbers here are not hand-written. The repository carries a release-please manifest and a matching config, and commitlint with husky hooks gates the commit format, so the commit format drives the next version number. The published sequence is dense: v1.274.1, v1.274.2 and v1.274.3 all landed on 2026-10-31. The licence is MIT, so embedding the UI inside a larger deployment carries no copyleft obligation, though the licence file is not legal advice and your own distribution terms still apply.

That density cuts both ways. The panel moves close behind the kernel, which means dashboard and mihomo versions can drift apart inside a single week. Pin the gh-pages pull to a commit you have actually looked at before putting it on a router you reach only over SSH.

Editorial conclusion

Adopt metacubexd if you already run mihomo on a machine you control and want a UI instead of editing config.yaml over SSH. Skip it if you were looking for a proxy client, because the panel container bundles no kernel and forwards no traffic of its own. Operators running a shared NAS should avoid the hosted sites entirely and serve the static assets themselves, so that no browser outside the network ever sees their controller secret. Before anything else, decide which of the three distributions you are running, then verify that external-controller is bound to the interface you actually intended, that external-controller-cors matches the dashboard origin exactly, and that the secret is not the placeholder value.

Frequently asked questions

What is mihomo?

mihomo is the kernel metacubexd is built to display, also known as Clash Meta. It exposes an HTTP external controller, and metacubexd is the web dashboard for that controller.

What is Clash Meta?

Clash Meta is another name for the mihomo kernel. The metacubexd config keys such as external-controller and external-ui belong to the mihomo configuration, not to the dashboard.

Does metacubexd include a proxy kernel?

Only two of its three distributions do. The standalone ghcr.io/metacubex/metacubexd container serves the dashboard on port 80 with no kernel bundled, while the desktop app and the all-in-one server image ship their own mihomo.

How do I update a self-hosted metacubexd?

If you cloned the gh-pages branch into the mihomo external-ui directory, update it with git -C /etc/mihomo/ui pull -r, as the README shows. If you run the container, pull the newer image and start it again.

Official sources

  1. License: MIT
  2. MetaCubeX/metacubexd on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/metacubex-metacubexd.svg)](https://hysenlabs.com/projects/metacubex-metacubexd)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/metacubex-metacubexd.svg)](https://hysenlabs.com/projects/metacubex-metacubexd)

Was this useful?