zashboard

Interaction

• Connection Table: Drag with the left mouse button; right-click to copy cell content.
• Speedtests: Right-click on a node or node group card to perform a speedtest.
• PWA: The dashboard supports Progressive Web App (PWA). You can use "Add to Home Screen" on mobile devices for a native app-like experience.

Node Group Sorting

Proxy group sorting is based on the node order in the GLOBAL group:

• Mihomo: Follows the configuration file order.
• sing-box: Places route.final first, followed by the configuration file order.
• Customization: To specify a custom order, override the GLOBAL group.

You can run zashboard as a containerized application using Docker. This will map the dashboard to port 80 on your host machine.

docker run -d -p 80:80 ghcr.io/zephyruso/zashboard:latest

Ensure your browser meets the following minimum versions for compatibility:

• Chrome: 111 (released March 2023)
• Firefox: 128 (released July 2024)
• Safari: 16.4 (released March 2023)

Note: Not supported on jailbroken versions of iOS 16.4.

To use the dashboard's upgrade button and auto-upgrade functionality, you must correctly configure the UI download path in your core's configuration. If this is not configured, clicking update may revert the dashboard to the core's default panel.

• Mihomo: Refer to Mihomo configuration docs.
• sing-box: Refer to sing-box configuration docs.

The Backend type defines how Zashboard connects to the underlying proxy core. It supports two types: clash (using Clash REST/WS API) and singbox (using sing-box native gRPC).

Key configuration fields:

• type: Either 'clash' or 'singbox'.
• password: Used as the Clash secret or the sing-box gRPC Bearer token.
• secondaryPath: Required only when type is 'clash'.
• disableUpgradeCore and disableTunMode: Specific to Clash backends.

You can pre-configure the connection to your backend API (Clash or sing-box) by using specific URL parameters in the setup path.

Basic Example Format: http://host:port/#/setup?hostname=ipordomain&port=9090&secret=123456

Parameters:

• hostname: The IP or domain of the Clash/sing-box API.
• port: The API port.
• secret: The authentication password.
• type: Selects the backend API. Options are clash (Clash REST/WS) or singbox (sing-box native). Default is clash.
• secondaryPath: (Optional) A path appended to the base URL. Default is an empty string.
• disableUpgradeCore: Set to 1 to hide the upgrade core button.
• disableTunMode: Set to 1 to hide the TUN switch.
• http / https: Determines the protocol. Defaults to the current page protocol.

Zashboard manages multiple API backends (e.g., Clash, sing-box) using a persistent list and an active selection. The backend list is stored in local storage under the key setup/api-list, and the currently active backend's ID is stored under setup/active-uuid.

• backendList: A reactive array of Backend objects.
• activeUuid: The uuid of the currently selected backend.
• activeBackend: A computed property that returns the full Backend object corresponding to the activeUuid.

The settings.ts module provides utilities for controlling the visibility of settings items and applying predefined visibility presets. It supports an 'edit mode' where all settings are rendered regardless of their hidden state to allow for in-place toggling.

Visibility Control

• settingsEditMode: A reactive boolean. When true, all settings items are visible.
• useIsSettingVisible(key): A composable that returns a computed boolean indicating if a setting is visible. Use this in Vue templates for reactivity.
• useHasAnyVisibleSetting(keys): A composable that returns a computed boolean indicating if at least one of the provided keys is visible.
• toggleSettingHidden(key): Toggles the hidden state of a specific setting key.

The probeSingboxChannel function performs a connectivity test to verify if a sing-box backend is reachable and responding. It attempts to call the getVersion method on the StartedService.

• Parameters:
  • backend: The Backend object containing connection details.
  • timeout: (Optional) The maximum time in milliseconds to wait for a response. Defaults to 10000 (10 seconds).
• Returns: A Promise<boolean> which resolves to true if the connection is successful, or false if the request fails or times out.

Zashboard uses localStorage to persist configuration. Settings are identified by keys starting with config/. You can use the following utilities to manage these settings:

• getDashboardSettingsFromStorage(): Retrieves all settings currently stored in localStorage that have the config/ prefix.
• applyDashboardSettingsToStorage(settings): Saves a record of settings to localStorage. Only keys starting with config/ will be persisted.
• exportSettings(): Triggers a browser download of a JSON file named zashboard-settings containing all current dashboard settings.
• resetSettings(): Removes all keys starting with config/ from localStorage and reloads the window.

The proxies module provides a unified facade for managing proxy groups and providers across different backends (Clash or sing-box). It maintains shared view state and provides helper functions to access proxy latency, history, and connection status.

Shared State

• proxiesFilter: A ref containing the current proxy filter string.
• proxiesTabShow: A ref indicating the current proxy tab type (defaults to PROXY_TAB_TYPE.PROXIES).
• proxyGroupList: A ref containing a list of proxy group names.
• proxyMap: A ref mapping proxy names to Proxy objects.
• proxyProviederList: A ref containing a list of ProxyProvider objects.
• IPv6Map: A useStorage reactive object mapping proxy names to their IPv6 status.
• hiddenGroupMap: A useStorage reactive object mapping group names to their visibility status.

Create a persistent WebSocket connection to the Clash backend for real-time data (like logs). The function handles reconnection automatically using ReconnectingWebSocket and provides a reactive data ref.

• url: The endpoint path (e.g., 'logs').
• searchParams: Optional key-value pairs to append to the WebSocket URL.