Clash Dashboard Guide: Setting Up a Visual Control Panel

Clash's core is a headless command-line process — but it ships with a full RESTful API that lets external tools query status, switch nodes, and update configuration in real time via HTTP. A Dashboard is a web front-end built on top of this API, giving you nearly complete control over Clash without ever restarting it. This guide walks you through API configuration and getting a full visual management setup running.

Enabling the External Controller

Clash's API server is activated by the external-controller field. Add the following to your config.yaml:

# Clash external controller settings
external-controller: 127.0.0.1:9090   # Local access only (recommended)
secret: your-api-secret               # Bearer token auth; leave empty to disable
external-ui: ui                       # Dashboard static files (relative to Clash home)
external-ui-url: https://github.com/MetaCubeX/metacubexd/archive/gh-pages.zip

Binding external-controller to 127.0.0.1 restricts API access to the local machine. If you need other devices on your LAN to access it (e.g., managing a router-based Clash from your phone), change it to 0.0.0.0:9090 — but always set a strong secret to prevent unauthorized LAN access.

Dashboard Options Compared

Several open-source dashboards are available, each with a different focus:

Setting Up Metacubexd (Recommended)

Metacubexd is the most feature-complete dashboard. The project offers an official CDN-hosted version that requires no local installation.

Option 1: Use the CDN-hosted version directly

Open your browser and go to https://metacubex.github.io/metacubexd/, then enter:

• Backend address: http://127.0.0.1:9090
• Secret: the value you set for secret in config.yaml

Option 2: Local installation (offline)

Create a ui/ folder inside Mihomo's home directory and extract Metacubexd's gh-pages branch into it. After starting Clash, visit http://127.0.0.1:9090/ui/ to access the locally hosted dashboard.

Dashboard Core Features

Proxy Node Management

The Proxies page displays all proxy groups and nodes as cards. Clicking a node inside a group switches to it immediately — no Clash restart required. Color indicators next to latency values (green/yellow/red) show node health at a glance. The "Test" button triggers a manual latency check for any group.

Real-Time Connection Monitoring

The Connections page is your best debugging tool. Every active connection shows: the destination domain/IP, the rule it matched (and which rule set it came from), the proxy group used, bytes transferred, and connection duration. If an app is taking the wrong route — e.g., something that should go direct is being proxied — you'll see it here immediately.

Rule Set & Provider Management

Mihomo's dashboard lets you view all loaded rule sets (Rule Providers), see when they were last updated, and manually trigger a refresh — no restart needed. Proxy Providers work the same way: you can pull updated subscription node lists without touching the config file.

# Trigger update for the rule set named "proxy-list"
curl -X PUT http://127.0.0.1:9090/providers/rules/proxy-list \
  -H "Authorization: Bearer your-api-secret"

# Trigger update for a proxy subscription
curl -X PUT http://127.0.0.1:9090/providers/proxies/my-subscription \
  -H "Authorization: Bearer your-api-secret"

Automation With the API

The Clash RESTful API goes well beyond what the dashboard exposes. With scripts, you can build powerful automation:

# Get all proxy node statuses
GET  /proxies

# Switch a proxy group to a specific node
PUT  /proxies/{group-name}
     Body: {"name": "node-name"}

# Real-time traffic stats (WebSocket)
GET  /traffic

# Live log stream (WebSocket)
GET  /logs?level=info

# Hot-reload config file
PUT  /configs?force=false
     Body: {"path": "/path/to/config.yaml"}

Combined with shell scripts or scheduled tasks, you can build things like "auto-update all rule sets and subscriptions at 3 AM daily" or "auto-switch proxy group when a node's latency exceeds a threshold" — a fully unattended proxy management setup.