Settings

General settings

You reach the PML 2 settings screen by clicking the gear icon on the left of the main screen. There you can configure the various PML 2 options. To edit the configuration file instead, see the configuration file section.

Appearance

Here you choose how PML 2 looks.

Theme

PML 2 offers several themes — light, dark and system (which follows the OS setting). Pick whichever you prefer.

Material

PML 2 lets you pick different materials such as Mica (Windows 11 only), Acrylic, Transparent and None. Different materials change the look and feel of PML 2.

Background (moved to the "Custom" options below)

You can pick a background image to personalise the PML 2 interface — choose a local image, or no background at all.

Background settings

Here you set the background image stretch mode. PML 2 offers several modes, including:

• Uniform: scales the image to fit the background area while preserving its aspect ratio, which may leave empty space.
• Fill: stretches the image to fill the background area, which may distort it.
• UniformToFill: scales the image to fit the background area while preserving its aspect ratio.
• None: the image is not stretched and may overflow the background area.

Custom

Here you can customise other PML 2 settings.

Background

Pick a background image to personalise the PML 2 interface. Recently used background images appear here so you can switch quickly.

Background opacity

Adjust the opacity of the background image. A better-balanced opacity makes interface elements easier to read.

Background fill mode (WIP)

Here you choose the background fill mode: only the main window, or the title bar as well.

Accent colour

Here you choose the PML 2 accent colour. Currently only custom accent colours are available. To restore the default, click "Restore".

Customise home page

Here you choose which controls appear on the home page.

Home layout (26.4)

Here you switch the home layout: classic (default) or compact. The change takes effect immediately, with no restart. See the "Home page" section below for the differences.

Startup settings

Here you configure how PML 2 starts.

Start with the system

Choose whether PML 2 starts automatically at boot.

Start some tunnels automatically on launch

Choose whether selected tunnels start automatically when the app starts.

Minimise to the tray instead of closing

Choose whether closing the app minimises it to the system tray instead of exiting. This keeps the app running in the background so you can reopen it quickly. Tunnels stay connected while it runs in the background.

Tunnel settings

Here you configure PML 2's tunnel behaviour.

Re-enable a tunnel right after it is force-disconnected

When the 幻缘映射 website force-disconnects a tunnel it also disables it. This option re-enables the tunnel for you, so a force-disconnected tunnel does not silently stay disabled.

"Tunnel monitor" bar BETA

The "Tunnel monitor" is a feature we introduced to watch the upload and download traffic of running tunnels.

Download settings

Here you configure PML 2's download options.

Enable multi-threaded downloads

Multi-threaded downloads can improve download speed.

Download thread count

Sets the number of threads. Too many threads can make downloads unstable, so tune it to your network and hardware.

ME Frp client download source

Sets the download source for the ME Frp client, for faster downloads. Several sources are available, including:

• Official: download straight from the official servers.
• TPCA: download from TPCA servers.
  By default PML 2 uses the TPCA source. If the client cannot be downloaded, try the official source — that resolves about 98% of download problems.

Account settings

Here you configure your PML 2 account options.

Days before sign-in expires

How many days of inactivity after signing in before the app signs out automatically.

Verification method

The human-verification method used when signing in. Two methods are available:

• Invisible verification: recommended. Nothing to solve — verification completes automatically during sign-in.
• Browser verification: you complete the check in a browser, then paste the result back manually to finish signing in.
  By default PML 2 uses invisible verification. If you hit a verification failure while signing in, try switching to browser verification.
  Browser verification originally existed to work around performance problems on Arm devices, but since invisible verification turned out to work fine on Arm too, it is now the default.

Other settings

Do not show successful request responses

More than one user told us that success responses get in the way of reading the screen, so this option hides them and lets you concentrate.

Update settings

Update settings live under " Update" in the left sidebar.

Here you configure how PML 2 updates itself.

Update mode

Which mechanism the app uses to update. Three modes are available:

• Check for updates and install automatically: recommended.
• Check for updates and download automatically: the latest installer is downloaded but not installed.
• Check for updates manually: you check and install yourself.

Keep configuration

Whether your configuration is preserved when the app updates.

Update channel

Controls which version the app updates to. Release cadence and stability differ per channel, and some channels may contain unstable features — use them with care. The available channels are:

• Stable: stable releases, with newer, well-tested features and improvements.
• Release preview: an early look at the next version, with newer features and improvements and possibly a few defects.

Tunnel management

Node latency and connectivity

Each tunnel card on the tunnel management page shows the connectivity of its node. Click "Refresh latency test" in the top toolbar to probe the latency of every tunnel's node in the list (TCP connectivity, probing node address:tunnel remote port).

• Probes are concurrency-limited (at most 6 at a time) and never block the UI; click "Cancel test" to stop mid-run.
• Status meanings:

• The probe target matches the access address shown on the tunnel card (node address:port), so it reflects the tunnel's real availability.

Creating a tunnel

The create page has three tabs (Guided / Expert / Jiahao), with "Refresh", "Back" and "Next" in the bottom command bar.

Creation modes (Guided / Expert / Jiahao)

Guided wizard

1. Pick a template: titled "Create tunnel wizard", it lists the available templates (icon + name + description). Templates are declared by plugins of type create-proxy-template (built-in templates work out of the box, and third-party plugins can add more). With no templates at all it says "No tunnel templates available. Install a create-proxy-template plugin first, or check that it is enabled on the Plugins page.".
2. Pick a node: candidate nodes are filtered by the template's requirements and you choose one (independent of the Expert tab's selection). Filtering rules: online + not overloaded + supporting every protocol the template needs (plus a bandwidth floor if the template declares one). With no candidates it relaxes to "online + supports the fallback protocol". Ordering prefers "allows heavy traffic", then lowest load. With no candidates it says "No node matches the requirements; please choose one manually".
3. Fill in and submit: the form pre-fills the proxy name (supporting {name} / {nodeId} placeholders), the local address (127.0.0.1 unless the template says otherwise), the local port and the remote port (auto-requesting a free remote port when the template says auto). The usual field validation still applies and you can keep tweaking.
4. Done: it reports "Tunnel created successfully". If the template declares an additional tunnel (for example the complementary TCP + UDP tunnel for remote desktop), that flipped-protocol tunnel is created too and it reports "Created a matching UDP/TCP tunnel with the same name".

"Refresh" in the guided mode only reloads the template list; candidate nodes are re-filtered against the current template the next time you enter the node step.

Local address pre-fill

The create form's "local address" defaults to 127.0.0.1 (the loopback address, which covers the vast majority of local services). Change the default in Config/Settings.json under CreateProxyDefaults.LocalAddress; it takes effect after a restart.

Common port shortcuts

Next to the "local port" field there are shortcut buttons for common ports: 80 (HTTP), 443 (HTTPS), 22 (SSH) and 25565 (Minecraft Java Edition). Clicking one fills the local port, and you can still fine-tune it.

Templates (apply / save / delete)

The "Templates" area at the bottom of the create page stores frequently used tunnel parameters so you do not retype them:

1. Save as template: type a name in the "Save current as template" box and click the button to save the form's local address, local port, protocol, remote port (TCP/UDP) and encryption/compression switches as a template.
2. Apply template: pick a saved template in the "Apply template" dropdown and click the button; its parameters fill the form (parameters that were not saved keep their current values). You can keep editing afterwards, with the usual validation.
3. Delete template: select a template and click "Delete template".

Templates persist in Config/Settings.json under ProxyTemplates and survive restarts. Saving a template with an existing name overwrites the old one.

Tunnel status and failure reasons

Each tunnel card on the tunnel management page shows a status badge (colour + text) that updates live as tunnels start, stop and run:

Failure reasons and copying

When a start fails (authentication failure, port in use, node unreachable, process crash, ...), the card shows the mapped failure reason in red (readable text rather than a raw log) together with a "Copy error info" button:

• Clicking "Copy error info" puts app version + mefrpc version + failure summary on the clipboard, ready to paste into feedback or a ticket.
• If the server never confirms the tunnel is online within 30 seconds of starting, it is judged "node unreachable" (timeout).
• While the status is "Failed", pressing Stop immediately returns it to "Stopped".

See the troubleshooting guide for the specific path to follow for each failure category.

Access address QR code (26.3.1)

On a tunnel card, "Copy access address" is a split button: the main button copies the address, and the dropdown contains "Generate access QR code".

The QR entry is only offered for tunnels that can serve a site (HTTP/HTTPS). Tunnels using other protocols show a plain copy button.

Clicking it first shows a confirmation dialog, "QR code generated. View it now?" with the options:

• View: opens the QR code window;
• Copy to clipboard: with a single domain it copies directly; with several it first asks "Choose the domain whose QR code to copy". The copied QR code is a standard black-on-white code;
• Close: leaves the clipboard untouched.

The QR code window

• Multi-domain carousel: when a tunnel has several access domains, each domain gets its own QR code, switched with the left/right buttons, the dot indicators, or the ← → arrow keys. It does not wrap around (the button greys out at the end), the position is shown as "current / total", and it ignores the mouse wheel so you cannot switch by accident while adjusting settings. With only one domain no switching controls appear.
• Customisation (scoped to the QR code currently shown, and kept when you switch domains): size, icon (pick a local image), icon size, foreground colour (defaults to the theme accent colour) and background colour.
• Export PNG: saves the current QR code as an image (with success/failure feedback).
• Copy to clipboard: copies the current QR code bitmap.

The QR code encodes the scannable access address: http://domain for HTTP tunnels and https://domain for HTTPS tunnels.

Updates

Checking and downloading

The "Update" page shows the current version, the latest version in the cloud and the changelog:

1. Check for updates: click it to fetch the latest version information. When a new version exists, its number and changelog appear along with a "Download and install" button.
2. Download the update: clicking "Download and install" downloads the installer for your system (an exe setup on Windows, dmg on macOS, deb on Linux) with a visible progress bar and live speed. When the download finishes it either installs automatically or opens the containing folder, according to the "update mode" setting.

Failures and retries

Update failures are never silent — the UI states what happened and what to do next:

Download source

The Settings page switches the download source (DownloadSource, TPCA by default):

• TPCA: the default source, covering application update packages and the mefrpc client.
• Official: the fallback. When the default source is unavailable (downloads keep failing, or the app tells you to switch), switch to "Official" and retry.

Application update packages currently only provide the default source (no automatic fallback); on failure the app suggests switching the source and retrying. The mefrpc client download already has two built-in sources and retries.

Plugins

Plugins page and form-based editor (26.3.1)

The "Plugins" page has three tabs:

• Plugins: locally installed plugins (enable/disable, uninstall), with "New plugin" and "Edit" entries at the top.
• Online plugins: browse and install from the official repository (sign-in required).
• Execution log: a live, incremental log of plugin triggers and action runs (capped at 200 entries in memory). States include event matched / condition not met so skipped / action succeeded / failed. The "Clear" button at the top empties the list.

"New plugin / Edit" opens a form-based editor: no YAML to hand-write. Fill in the plugin ID, name, event (triggers.on), condition expression and action parameters using dropdowns and fields. You can preview the generated YAML at the top, with live validation (saving something invalid shows the specific error). The editor's dropdown options (events/actions) come from the same source as the runtime engine, so "if it can be written, it can run".

Plugin files

Plugins live in Config/Plugins/*.yaml and support hot reload (a changed file takes effect within 1 second). See plugin event triggers for the full list of events and condition expressions, plugin operators for operators, and plugin development overview for the system as a whole.

Home page (26.4)

The home page supports two layouts, switched under "Settings → Appearance → Customise home page → Home layout". The change takes effect immediately, with no restart.

Compact layout

It keeps only three core blocks:

1. Account bar: a time-of-day greeting, remaining traffic and the number of running tunnels. When signed out it shows "Sign in"; when signed in you can jump to the user centre in one click. On the right is the inbox button, showing a red dot and the count of new items.
2. My tunnels: lists tunnel rows directly (failed first → running → by name, at most 8). Each row shows a status dot, type, node and access address, and offers one-click start/stop and copy access address. Failed rows also show the failure reason. The header row shows running/failed counts, "Refresh" (re-fetches tunnel data only), "Manage", and an available-update entry (only when an update exists). With no tunnels it points you to the create page.
3. Quick create + recommended for you: HTTP / HTTPS / TCP / UDP jump to the create page with that protocol preselected. The recommendations area holds up to 5 entries, each with a title + explainable reason + one-click action, plus a "Ignore for now" button.

Recommendations are produced by priority (a rule engine, not AI):

"Start a recently used tunnel"

The recommendations area lists the tunnels you started most recently, newest first, each with a one-click restart so you do not have to find it in the management page again.

• Where the data comes from: the tunnel's last start time as recorded by the server, compared with the local record, whichever is newer. So a tunnel you just started shows up in the recommendations immediately, without waiting for the server, and after signing in on another device the list is restored from the server record.
• Time display: the reason text gives a relative time such as "just now", "23 minutes ago", "3 hours ago" or "2 days ago".
• When it is not shown: the tunnel is already running (no need to start it twice), has been disabled or banned, the account is disabled or over quota, or it has never been started.
• Tunnel deleted: clicking it reports "That tunnel no longer exists" and removes it from the recommendations.

"Ignore for now" is stored in Cache/home-recommend.json and is not written to the user configuration; an ignored entry does not come back.

Classic layout (default)

Keeps the full 26.3 home page: platform statistics, the user information panel and system/software announcements, controlled by the switches under "Customise home page". Those switches have no effect in the compact layout (they are greyed out with an explanation), and the inbox button is only available in the compact layout (in the classic layout announcements are shown directly in the "System announcements / Software announcements" panels).

Inbox (26.4)

The inbox button on the right of the compact home page's account bar collects two kinds of notification:

• New-content indicator: the red number on the button is new system notifications + new software announcements. It is computed as a local snapshot difference (the snapshot lives in Cache/inbox-notice.json and is not written to the user configuration) — only entries appearing for the first time count as "new", and they disappear again if an announcement is withdrawn.
• When it is marked read: the snapshot is only written back once you actually open the inbox (opening counts as reading), so unseen notifications keep showing the red dot instead of being silently marked read.
• Data loading: the inbox makes no network request of its own; it reuses the home page results and the shared 5-minute cache (see "Data caching" below).
• Empty state: with nothing to show it displays "No notifications". An image-only announcement with no extractable text shows an explanatory message rather than a blank card.

What's new prompt (26.4)

The first launch after an upgrade shows a "What's new" window with the current version number, codename and date. Once confirmed it does not appear again — the same version never interrupts you twice (and nothing appears when the version has not changed).

The window has two source tabs:

• The change entries and wording are served by the server or the blog, so notes can be updated at any time without shipping a new release.
• When the server is unavailable the tab degrades to "Update notes are temporarily unavailable; you can check the Update page later." and startup is unaffected.
• Buttons: "Go to the update page" (closes the window and opens the update page for the full history) and "Got it" (closes).

Certificate assistant (26.4)

The "Certificate assistant" requests SSL certificates for domains you own, for use when creating HTTPS tunnels. Entry point: Settings → Tunnel settings → Certificate assistant. In the same group, Settings → Tunnel settings → DNS accounts stores DNS provider credentials for one-click automatic verification.

This feature is unrelated to the certificate service of 幻缘映射 ME Frp. Your domains, ACME email address, certificates and private keys, and DNS credentials are all processed locally only.

Verification method

The "verification method" in the window decides who adds the TXT record:

• "DNS account (one-click automatic)" is selected by default. Switching to "Manual DNS" hides the DNS account dropdown and the "Manage DNS accounts" button and switches to the manual TXT flow.
• The environment defaults to Staging (test). Switching to Production shows a rate-limit warning and asks for confirmation when you click "Start request".
• The propagation wait limit and "skip propagation check" live under "Advanced options" (see below).

In DNS account mode, when no account is configured it says "No accounts available; add one under DNS accounts first", and you can click "Manage DNS accounts" to add one or switch to "Manual DNS".

DNS accounts

Once a provider credential is saved you can request certificates in one click:

1. Provider: the first batch supports Cloudflare, Alibaba Cloud DNS and DNSPod. Providers that are missing can be requested through "Submit a DNS provider".
2. Account name: a label of your own (such as "CF-primary"), used to tell accounts apart in the certificate assistant.
3. Credentials: fields depend on the provider (Cloudflare uses API Token; Alibaba Cloud uses AccessKey ID / AccessKey Secret; DNSPod uses SecretId / SecretKey). Fields marked optional may be left empty. The UI gives least-privilege advice and a "How to create a token" link.
4. Where it is stored: credentials are encrypted and kept locally. They are never uploaded and never appear in logs or crash reports (tokens and keys in logs are sanitised automatically).
5. Deleting an account: certificates already issued keep working, but you can no longer request new ones with that account.

Request flow

1. Choose the environment: Staging (test) by default — its certificates are not trusted by browsers and exist only to validate the flow. Switch to Production once you are happy (issuance is rate-limited and asks for confirmation) .
2. Enter the domain and email: the primary domain (such as example.com) plus the ACME account email (pre-filled with your current account email). For "additional domains (optional)" separate several with commas (such as www.example.com) .
3. Choose the verification method: see above. Choosing "DNS account" also requires picking the specific account.
4. Click "Start request": on first use lego is downloaded for your platform (about 20 MB) and verified against the official SHA-256. Failures can be retried (the app tries the primary source and the fallback mirror in turn) .
5. Complete domain verification:
   • DNS account: the record is published automatically, and the UI steps through "Publishing the validation record through the DNS API…" → "Waiting for DNS propagation and CA validation…" → "Issuing and assembling certificate files…" → "Cleaning up the validation record…".
   • Manual DNS: the window shows the record host (_acme-challenge.your-domain) and the record value, each with a "Copy" button. Add that TXT record at your DNS provider and wait for it to take effect (usually a few minutes), then click "I have added it". From there the app waits up to 5 minutes (DNS propagation and CA validation) .
6. Done: the window shows the certificate directory path. "Open certificate directory" reveals the artefacts, "Copy" copies the certificate and key paths, and "Use for tunnel" explains how to use the certificate in a tunnel.

Advanced options and runtime log

• Wait limit (seconds): the longest wait for DNS propagation and CA validation. 300 by default, adjustable from 60 to 900; raise it on a slow network or when records take a while to take effect. The same value is used for lego's command-line argument and the provider environment variable, so the two can never disagree.
• Skip DNS propagation check (not recommended): off by default. When enabled it waits a fixed 30 seconds instead, which can make CA validation fail and burn issuance quota. Only use it on unusual networks.
• Runtime log: the window shows lego's output live during a request, with tokens and keys sanitised, which is useful for self-diagnosis (the collapsible "Runtime log" section) .

Local certificates (view and delete)

The "Local certificates" section lists the certificates already issued under Config/Certificates/ (domain, additional domains and certificate chain paths; ones nearing expiry are marked "Expiring soon"). Each row can be deleted:

• Deleting removes the whole certificate directory (private key included). Tunnels currently using that certificate are unaffected, but it can no longer be picked through "Select from certificate assistant".
• Deleting asks for confirmation, and the list refreshes automatically after a successful request.

Artefacts and their use

Location: Config/Certificates/{domain}/.

Using it in an HTTPS tunnel

When creating or editing an HTTPS tunnel, the "certificate path" row has a "Select from certificate assistant" button on its right:

• Picking an issued certificate fills in both the "certificate path" and the "key path";
• Picking a Staging certificate warns "Staging (test)", and one less than 30 days from expiry warns "Expiring soon (N d)", which prevents mistakes;
• When there are no local certificates it says "No local certificates" and offers to open the certificate directory.

Common failure reasons

Not supported yet

• Certificate auto-renewal and bulk issuance, and revocation management;
• DNS providers beyond the first three (Cloudflare / Alibaba Cloud DNS / DNSPod) — request them through "Submit a DNS provider" so we can add support.

Data caching (26.4)

From 26.4 onwards the app caches API data for all pages with a uniform 5-minute cache, reducing duplicate requests and speeding up page changes.

Rules

What triggers an immediate refetch

These actions bypass the cache and always fetch fresh data, so what you see matches the server:

• Clicking a page's "Refresh" button;
• "Refresh" on the compact home page (whole page) and "My tunnels → Refresh" (tunnel data only) ;
• "Refresh tunnel list" in the top bar menu;
• "Check for updates" on the update page;
• "Reload" on the traffic chart;
• "Refresh" on the create-tunnel page (node list and status) ;
• After any write: creating / editing / deleting a tunnel, enabling / disabling a tunnel, force-disconnecting, checking in, or adding / removing a registered domain.

Data that is never cached

One-off actions and sensitive data are still requested live: the quick-start token, tunnel launch configuration, free-port requests and human verification. The inbox's "new content" determination also does not rely on the cache — it uses the local snapshot difference (see "Inbox" above).

Switching accounts

The cache is isolated per signed-in account: switching accounts never shows the previous account's data, and signing in or out clears the whole cache.

Manual cleanup

About → Toolbox → Clear cache empties the in-memory API cache as well as deleting disk files.

Splash screen (26.3.1)

At startup the app first shows a separate splash window (brand image + theme styling) whose progress bar and text update live with the startup stage (initialising the theme → creating the main window → loading the tray/plugins, ...). Progress is pushed from the main program over a dedicated named pipe (tech.rycb.pml2.splash.{pid}), kept strictly separate from the single-instance activation pipe, and the splash process exits by itself once the main window appears.

"Settings → Appearance → Splash screen" configures it (new in 26.3.1):

These changes take effect on the next start.

Desktop integration

Native macOS menu

On macOS the app menu bar provides native menus (reorganised into six menus in 26.3.1, with commands coming from exactly the same source as the main screen and the tray):

• PML 2 (app menu): About, Settings (⌘,), Quit (⌘Q) .
• File: Open log directory (jumps straight to Logs/ for troubleshooting) .
• Tunnels: Manage tunnels (⌘M), Create tunnel (⌘D), Stop all tunnels, Refresh tunnel list.
• Nodes: Node monitoring, Refresh nodes (re-entering the monitoring page refetches the data automatically) .
• View: Main window (show and focus the main screen), Traffic overlay (toggle) .
• Help: Official documentation, Check for updates.

Closing the window vs quitting: on macOS the red button (close window) equals quitting by default. If "Minimise to tray instead of closing" (HideInsteadOfClose) is enabled in Settings, closing leaves the app in the tray/menu bar and you quit via the menu or ⌘Q.

System tray

Windows, Linux and macOS all provide a tray icon whose context menu contains:

• Open main screen: shows and focuses the main window (prompting you to sign in when you are signed out) .
• Open terminal: switches to the terminal page.
• Stop all tunnels: sends Ctrl+C to every terminal, stopping all tunnels.
• Quit: stops all tunnels and then exits the app.

Tray actions and the main screen stay in sync in real time (tunnels are stopped/started on the terminal page; the tray menu holds no state of its own) .

Traffic overlay

After enabling "Traffic overlay" (PMSettings.Enabled) under "Settings → Overlay", a translucent traffic monitor bar appears in a screen corner (top right by default):

• Tunnel status: lists the running tunnels (coloured dot + name) and stays in sync in real time with the main screen — starting shows "Starting" (blue), the server confirming it online turns it "Running" (green), and a failure shows "Failed" (red, hover for the reason). When a tunnel stops (the stop button on the management page, Ctrl+C in the terminal, or "stop all") its entry is removed automatically, matching the behaviour when a terminal tab is closed.
• Live traffic: shows the instantaneous upload/download speed, with a line chart beneath plotting the last minute (30 samples) — green for download, blue for upload.
• Click-through (off by default): when enabled, mouse clicks pass through the overlay instead of affecting the window beneath it. While click-through is on, moving the pointer over the overlay temporarily disables it so you can use its menu.

Clicking the ⋯ menu on the bar:

• Refresh traffic: re-acquires the network interface and resets the traffic baseline (the chart clears and redraws) .
• Settings: opens the overlay settings (position, click-through, show traffic chart, opacity — all applied live and persisted in PMSettings) .
• Close overlay: closes only the overlay, not the app (the overlay is destroyed automatically when the app exits, with no stray always-on-top window) .

The overlay only shows traffic and provides the shortcuts above; it is not a full tunnel manager (use the main screen for that) .

Start with the system and restoring tunnels

The Settings page has two independent switches, both off by default:

• Tunnels are only started automatically when "Restore previous tunnels" is explicitly enabled and the auto-start queue is configured.
• Auto-start or restore failures are written to the log and reported in the UI; they never fail silently.
• Risks: enabling auto-start makes the app run at sign-in, and restoring tunnels consumes local ports and traffic. Configure it to suit your needs.