Clash Advanced Configuration Guide

01 · Configuration Flow and a Safe Baseline

The Client, Core, and Runtime Configuration

The client interface handles subscription imports, saves preferences, and starts background services. The core parses rules, establishes connections, and forwards traffic. A toggle in the interface does not mean the subscription file contains a field with the same name; conversely, a field added to the file may be overwritten when the client generates the runtime configuration. When troubleshooting, first check the core information or logs to confirm which core is running, then locate the configuration actually passed to it. Don't rely on the subscription editor alone.

This site organizes client downloads by platform. Start with Clash Plus when comparing options, then check other clients against your operating system and required features. Configuration entry points and merge behavior vary across Clash Verge Rev, Clash Meta for Android, FlClash, and other clients. To choose a different installation option, visit the client downloads page. The steps in this guide are not universal across platforms; check field support against the core actually in use.

Make Changes You Can Roll Back

Before making changes, save the subscription source, local overrides, and a working copy of the current runtime configuration. Record the original system proxy and TUN settings as well. Subscription URLs may contain access credentials; don't share them in public repositories, screenshots, or support posts. Change one configuration layer at a time: first confirm the file loads, then verify rule matching, and only then adjust traffic capture. Changing DNS, routing, and rule providers all at once makes it difficult to identify what changed the traffic path if connections fail.

This snippet illustrates basic fields; it is not a complete subscription with proxy nodes. It uses rule mode and a mixed port, with unmatched connections sent directly. When merging it into an existing configuration, edit the existing top-level field instead of adding a second rules key at the end of the file. YAML parsers may handle duplicate keys differently, so don't assume the later value will always override the earlier one.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

Use spaces consistently for indentation, keeping list-item dashes at the correct level under their fields. Quote strings containing colons or hash marks, or that could be interpreted as special values. The most common formatting problems aren't complex fields but lost indentation when copying snippets, or nesting a complete configuration under a child field. A file looking correct in the editor doesn't mean the core can parse it; check the load result after saving.

Check Syntax and Behavior Separately

If you have a standalone Mihomo executable, you can start by running the test command below. The file must be in the current directory. If rule providers, databases, or other dependencies use relative paths, the test working directory must also match the actual runtime environment. Passing a syntax test only means the configuration parses; it does not confirm that nodes work, DNS is reachable, or system routes are in place.

mihomo -t -f ./config.yaml

Check behavior layer by layer using a new connection: does the application reach the core, is the destination domain recognized, which rule matches, and which outbound is selected? Existing browser connections may keep using an earlier policy. Start a new request and, if needed, close and reopen the application. Don't assume a new rule is working just because an old browser tab still loads after you switch proxy groups.

If even a minimal configuration won't start, check for port conflicts, file permissions, and incorrect paths before investigating rule syntax. If you see an address-in-use error, follow the guide to diagnosing a port 7890 conflict and changing mixed-port. After changing the port, update any manually configured proxy settings too, or the core may listen on the new port while the browser still connects to the old one.

02 · Proxy Group Types and Practical Layering

Separate Rule Targets from Actual Outbounds

Rules answer “which policy handles this connection?” Proxy groups answer “which outbound should be selected from these candidates?” A rule can point to a specific node or to a proxy group. For day-to-day configurations, have rules reference stable group names and manage node changes inside those groups. That way, subscription updates that rename nodes won't force you to edit every traffic rule. Group names are identifiers: spaces, capitalization, and spelling must match exactly.

select is a manual selection group, suited to a user-facing entry point. url-test selects a candidate based on probe results. fallback prefers the first available outbound in the list. load-balance distributes different connections across candidates according to the selected strategy. Each type solves a different problem; don't assume “automatic” is always better than “manual.”

Separate the entry group from automatic selection

A maintainable setup is to have rules point to “Network Exit,” then let that entry group offer an automatic group, manual candidates, or a direct connection. The snippet below uses only the built-in DIRECT outbound to demonstrate group references; it does not provide a proxy connection. For a working setup, add real candidates from a subscription you are authorized to use or from local node definitions, then list them in the automatic group. Don't mistake this example for a source of proxy nodes.

proxy-groups:
  - name: Network Exit
    type: select
    proxies:
      - Automatic Selection
      - DIRECT

  - name: Automatic Selection
    type: url-test
    proxies:
      - DIRECT
    url: https://example.com/
    interval: 300
    tolerance: 50

rules:
  - DOMAIN-SUFFIX,example.com,Network Exit
  - MATCH,DIRECT

Here, interval sets the probe interval, while tolerance helps prevent frequent switches caused by small differences in probe results. Choose a test endpoint that candidates can reach and that gives clear, consistent responses. The example domain is for illustrating the fields only; use a probe target suited to your network in production. A probe measures the route to that endpoint, not download speed, video availability, or the reliability of a particular account or service.

For sign-in sessions, payment pages, or services sensitive to your outbound IP, use a manually selected group to avoid switching exit addresses across new connections. Even a consistent load-balancing strategy can't guarantee that all related domains use the same address: a page may depend on several services, and the candidate pool can change. If you need a stable exit, check actual connection records rather than relying on the group name.

Avoid Circular References and Missing Candidates

Proxy groups can reference other groups, but they must not form a cycle. For example, if an entry group references an automatic group that then references the entry group, selection has no clear endpoint. Keep the hierarchy one-way: traffic rules point to an entry group, the entry group points to functional groups, and those groups point to real nodes or built-in outbounds. For provider references, check that the names in use exist and that the providers loaded successfully.

If a group appears but has no selectable nodes, first check whether its filter expression excludes all candidates, then review the subscription load logs. Don't immediately replace the filter with a more complicated expression. Duplicate node names can also make the displayed choices and references ambiguous, so set a unique naming convention before merging subscriptions. If every candidate in an automatic group fails, test a known candidate on its own to distinguish a node connectivity issue from an unreachable probe target.

After changing a group selection, check new connections only. Some clients save the previous selection and restore it on restart; that is separate from the order of items in the YAML list. If the interface selection differs from what you expect, check both the client's persisted settings and its current runtime state. For a comparison of client controls, see the client comparison rather than repeatedly renaming groups to work around saved state.

03 · Rule Providers and Matching Order

Separate Rule Content from Traffic Destinations

As domain and IP range entries grow, keeping them all in the main configuration makes updates and review harder. rule-providers defines where rule content comes from, while RULE-SET references it in the main rule list and specifies the policy for matches. Rule sets define “which destinations”; the main configuration defines “where they go.” Keeping them separate lets the same list of service domains point to different proxy groups on different devices.

The provider's behavior must match its contents: domain is for domain lists, ipcidr for IP ranges, and classical for entries using traditional rule types. A reachable download URL doesn't guarantee the file is in the right format. Reading YAML with a payload field as a plain-text list, or passing complete rule lines to a domain parser, can cause load failures or unexpected results.

Start by Testing References with a Local File

This example uses a local file so you can verify rule provider references without relying on a remote download. First create a rules directory in the core's working directory, then save local-domains.yaml there. The file contains rule entries only, not proxy policies. The example domains are for testing matches; replace them with domains you actually need to manage and keep a record of your changes.

# rules/local-domains.yaml
payload:
  - '+.example.com'

Define the file source in the main configuration, then reference it in the regular rules. Relative paths are resolved from the core's working directory, not necessarily the editor file currently open in the client. In a desktop client, find out which configuration directory it assigns to the core. Otherwise, you may save the file in your downloads folder while the runtime looks elsewhere.

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,DIRECT

To switch to an HTTP source, set a reachable url, a cache path, and an update interval. Confirm that the server returns the rule content itself, not a preview page or login screen. Give each provider a unique cache path; don't let two providers write to the same file. Use a YAML, text, or compiled format supported by the core, and make sure the declared format matches the content. Changing the file extension alone isn't enough.

Rule Order Determines the Outcome

Rules are generally checked from top to bottom, and the first match ends the evaluation. Put specific domain exceptions before broader categories, then use MATCH for all remaining traffic. A rule set added after MATCH won't have the expected effect. Likewise, a broad domain suffix rule placed too early can prevent more specific rules below it from ever matching.

IP-based rules may trigger domain resolution. Some rules support the no-resolve option at the end, which prevents an additional lookup for an IP rule when the destination is still a domain. It does not mean “disable DNS for the whole connection.” To give domain rules priority, put them before IP-range rules that require resolution. Adding this option everywhere to reduce lookups can break rules that rely on resolved addresses.

If a remote rule provider fails to update, first check whether the core still has a usable cached copy, then investigate the download path and access requirements. Initial startup differs from routine updates: an update may be able to use an old cache, while a first launch may have no content at all. If downloading rules requires a proxy, but choosing that proxy depends on rules that have not yet been downloaded, startup can get stuck in a dependency loop. Keep the initial connection path simple.

For frequently updated rule sources, keep a snapshot of the previous content and check after each update whether important service domains have been assigned to new categories. GeoIP, GeoSite, and ordinary rule providers do not use identical storage mechanisms. For database formats, paths, and update conditions, see the GeoIP and GeoSite database update guide. Don't replace files from different mechanisms just to make their names consistent.

04 · DNS Resolution Paths and Configuration

Separate Application, Core, and Proxy Node Lookups

DNS problems are often less about whether a resolver is configured and more about which component sends the query. A browser may use its own encrypted DNS, the operating system may cache an old result, and the core may also need to resolve a proxy server's hostname. The system proxy affects requests from applications that honor proxy settings; it does not automatically route every DNS query through the core. Before making changes, determine whether the application uses system DNS, the core's DNS, or a separate resolution path.

nameserver specifies regular DNS upstreams. default-nameserver handles basic startup needs, such as resolving the names of DNS upstreams. proxy-server-nameserver lets you separately choose how proxy server hostnames are resolved. Keeping these paths separate avoids requiring an established proxy connection to resolve the address needed to establish that connection. Switching all upstreams to HTTPS alone does not remove this dependency.

Start with a DNS Setup You Can Understand

This snippet runs a DNS service on a non-standard port at a loopback address and uses Fake-IP. It does not change the operating system's DNS settings by itself; queries must actually reach this listening port for it to have an effect. A desktop client's TUN interception, system DNS settings, and manual tests may each use a different path. Be clear about which one you're testing.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://1.1.1.1/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query

The upstream addresses here are examples, not a guarantee that they are reachable on every network. Choose upstreams based on local access, privacy requirements, and whether the results suit your needs. ipv6: false controls AAAA responses from this DNS configuration; it does not disable IPv6 across the operating system. If your network has working IPv6, turning this off may also change existing connection paths. Make changes to address a specific issue.

Choose Resolvers by Domain

Corporate domains, home device names, and certain service domains may only resolve correctly through a designated resolver. In that case, consider using nameserver-policy to send those domains to a dedicated upstream. Don't send internal domains to public resolvers by default: they may not resolve, and doing so could expose names meant to stay within your network. First define the domain scope carefully; an overly broad suffix could route many public queries to an internal server.

If you use respect-rules to make DNS upstream connections follow traffic rules, also consider how proxy server hostnames are resolved. This option changes the path the core uses to reach DNS upstreams; it does not automatically classify every DNS response correctly. Set up a separate, reachable path for resolving proxy nodes, then check which rule matches upstream connections. This avoids a loop where node resolution waits for a node connection that itself needs node resolution.

fallback and fallback-filter are not simply switches that use a backup when the primary server fails. Once enabled, result filtering depends on conditions such as domain names and address ranges. If you don't have a specific filtering goal, stick with a single reliable resolution path. Add fallback behavior only after confirming a particular class of domains has a specific resolution problem. More upstreams don't necessarily make DNS more reliable; they can just make troubleshooting harder.

dig @127.0.0.1 -p 1053 example.com A

When testing, record query time, returned address type, and core logs. In Fake-IP mode, an address from a reserved range may be an expected result, not a sign of DNS failure. After changing resolution modes, application or system caches may still hold old results. Make a new request and flush caches using the operating system's recommended method instead of continually adding more DNS upstreams.

If a domain resolves but the site won't load, check the connection's rule and outbound next. If only the browser behaves differently, check its independent DNS settings and proxy extensions. Follow the troubleshooting checklist for being connected but unable to access websites to investigate symptoms step by step. The goal of DNS configuration is a clear, verifiable resolution path—not the largest possible number of fields.

05 · TUN Traffic Capture and Fake-IP Mapping

What Each Mechanism Does

TUN creates a virtual network interface so the operating system can route IP traffic that matches its routing conditions to the core. Fake-IP returns a controlled virtual address during DNS resolution and stores a mapping to the original domain in the core. TUN answers “how does traffic reach the core?” Fake-IP helps answer “which domain did this traffic originally target?” They are often used together, but they are different features; enabling one does not necessarily replace the other.

The system proxy relies on applications honoring proxy settings, so it may not affect applications that ignore them. TUN captures a wider range of traffic through routing, but also involves permissions, a virtual network adapter, system DNS, and other VPNs. Broader traffic capture does not mean every protocol is automatically supported remotely; the outbound node's capabilities still determine what works. UDP in particular needs support across the entire path, from the application through the core to the remote endpoint.

Enable TUN Through the Client's Permission Flow

On desktop, use the client's service installation or authorization flow before enabling TUN. Windows often requires a background service or administrator privileges. On macOS, grant the required system permissions through the client. On Linux, behavior depends on service permissions, network management, and routing. Android usually requires authorization through the system VPN service; whether the relevant fields are exposed depends on the client. On iOS, network traffic capture is managed through app and system extension mechanisms, so desktop-level network adapter instructions do not apply.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

This snippet depends on the core DNS enabled in the previous section and assumes the client supports the relevant TUN settings. auto-route attempts to add the required routes, while auto-detect-interface attempts to identify the outbound interface. Automatic detection may not match the actual network topology with multiple adapters, containers, remote desktops, or corporate networks. Choose stack based on platform support and application behavior; no single stack is right for every device.

The dns-hijack example targets traditional DNS ports. It does not mean browser DoH or other encrypted DNS has been decrypted or replaced. Some applications connect directly to fixed IP addresses or use their own resolver, so check connection records to understand what is happening. If an application never appears in the core's connection list, investigate routing and the traffic capture path before changing domain rules again.

Use Fake-IP Filters Only for Necessary Exceptions

Some applications that depend on real IP address responses may not work well with Fake-IP—for example, certain local network discovery, device connections, or authentication flows. You can add specific domains to fake-ip-filter so those queries return real DNS results. Before adding exceptions, check the semantics of fake-ip-filter-mode. The same list can mean opposite things in different filter modes, so don't copy a long list from someone else without checking it.

Overly broad filtering reduces the core's ability to recover domain names from mappings and can change which rules match. Troubleshoot one affected domain at a time: confirm the query reaches the core, check the returned address type, and then see whether the connection requires a real IP. Device discovery may also rely on broadcast or multicast; adding a domain filter alone won't fix every local network access problem.

When using TUN alongside another VPN, clarify which one controls the default route and DNS, and check for overlapping traffic capture. Two virtual adapters advertising similar routes can cause requests to take unexpected paths, loop, or reach only some destinations. Disabling traffic capture on one of them and testing again is a useful way to isolate conflicts. Don't add stricter routing options without understanding the network topology.

To roll back, turn off TUN first, then confirm the system proxy and DNS have returned to their expected settings. After switching between Fake-IP and real DNS, refresh the relevant caches and establish new connections. If the client has exited but the network still behaves unexpectedly, check whether its background service is still running and whether manual proxy settings remain in the system. For general issues, see the Help Center and note the last network layer changed before the problem began.

06 · Domain Sniffing and Its Limits

Sniffing Adds Context to Connections

When a connection reaches the core with only a destination IP, domain rules may not have enough information to match. Domain sniffing attempts to extract a hostname from the protocol handshake, such as the host information in an HTTP request or the server name in a TLS handshake, for use in subsequent processing. It cannot decrypt arbitrary HTTPS content or automatically map every IP back to a unique domain. When multiple sites share an address, the address alone cannot identify which service is being accessed.

Sniffing and Fake-IP can both help preserve domain context, but they get it from different sources. Fake-IP relies on DNS mappings handled by the core; sniffing relies on protocol data visible early in a connection. If an application bypasses the core's DNS, sniffing may provide some of the missing context. But if the handshake does not expose a usable domain, or the protocol is unsupported, sniffing cannot invent one.

Limit the Protocol and Port Range First

This snippet shows basic HTTP and TLS sniffing while preserving the original connection destination. Start with a narrow port range and observe the results, then expand it for specific applications as needed. This is easier to troubleshoot than covering every port from the outset. The example port ranges are configuration conditions; they don't mean all traffic on those ports necessarily uses the corresponding protocol.

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
      override-destination: false
    TLS:
      ports:
        - 443
        - 8443

parse-pure-ip allows sniffing to be attempted for connections addressed to an IP. force-dns-mapping is related to DNS mapping scenarios; whether either is needed depends on the original connection details. override-destination determines whether sniffed results can rewrite the connection destination, rather than just add domain information. Before enabling it, distinguish between wanting rules to recognize a domain and wanting to change the final connection target.

Keeping the original address makes it easier to compare behavior before and after changing a setting. For services that depend on a specific address, private DNS, or a dedicated entry point, rewriting the destination could trigger additional lookups and send requests to a different server than intended. If destination rewriting is needed, test it with one application and one domain first. Don't treat it as a general fix for connection failures.

Exclusions and Cases Sniffing Can't Handle

For services that are incompatible with sniffing, use the domain or address exclusion fields supported by the core to create exceptions. Base exceptions on reproducible compatibility issues rather than copying an unexplained skip list. Record the destination address, sniffed domain, and matched rule before and after exclusions to identify whether the issue is in detection or in subsequent policy selection.

QUIC uses a different transport from conventional TLS. Relevant details can only be extracted if the corresponding parsing capability is enabled and supported by the core. Even then, not all information in an encrypted handshake is visible. Connections using ECH may no longer expose a usable target name. Private protocols, applications connecting directly by IP, and connections with no hostname information may not yield a domain that domain rules can use.

Don't block a protocol just to make domain names appear in logs. Blocking UDP may make some applications switch transports, or it may break them outright. If you need to run a compatibility test, document the conditions and restore the original settings afterward. Configure for application requirements, not to make the connection list look tidy.

Compare Connection Records Before and After

To test, first turn off sniffing, make a new request, and record the destination type, matched rule, and outbound. Then turn sniffing on and make a new connection for the same service. If a domain appears but routing doesn't change, an earlier IP rule may have matched first, or the domain rule may not cover that destination. If the connection fails after sniffing is enabled, first check whether the destination was rewritten and whether the additional lookup succeeded.

Limit the scope of saved test logs. Domains, request paths, node names, and controller details may reveal personal or organizational network activity. When asking for help, share only the necessary fields and redact sensitive information. For basic issues such as “all nodes timed out,” sniffing is rarely the first thing to check. Follow the troubleshooting steps for subscriptions, system time, and protocol compatibility to confirm that outbounds can connect before optimizing domain detection.

07 · Local Overrides and Merged Subscriptions

Separate Updatable Content from Device Settings

Subscriptions are suited to maintaining nodes, groups, and provider-managed rules. Local configuration is better for device-specific settings such as ports, TUN, local network access restrictions, and personal routing exceptions. Editing the subscription itself often means changes disappear at the next update. Client override, merge, or enhancement features let subscriptions keep updating while device-specific settings are managed separately.

Clients don't all define “override” in the same way. Some merge objects, some replace entire fields, some run scripts, and some force interface settings into the configuration at the end. In particular, don't assume arrays such as rules and proxy-groups are always appended item by item. Check the processing order before making changes, then inspect the final runtime configuration. The override editor alone can't confirm the end result.

Organize Multiple Sources with Proxy Providers

You don't necessarily need to concatenate complete files to combine multiple subscriptions. For node sources in a supported format, define separate proxy-providers and reference them in proxy groups using use. This example uses a file-based source so you can verify the structure first. You must prepare an actual node file in the core's working directory; until then, this snippet is not a complete configuration that can start on its own.

proxy-providers:
  personal-nodes:
    type: file
    path: ./providers/personal.yaml

  work-nodes:
    type: file
    path: ./providers/work.yaml

proxy-groups:
  - name: Personal Route
    type: select
    use:
      - personal-nodes

  - name: Work Route
    type: select
    use:
      - work-nodes

A provider file should contain a proxies list in the format required by the core, not an arbitrary client configuration with a full set of rules. A collection of encoded share links, a complete Clash configuration, and a proxy provider file are different formats; confirm the client or source supports the conversion before importing. Don't send a private subscription to an unknown online conversion service. Once a subscription URL or node credentials leave a controlled environment, access may be exposed.

If a source supports HTTP providers, give each one its own cache path and update interval. Separating personal and work sources clarifies group boundaries and makes it easier to disable one source for testing. Check that your use is authorized; the ability to merge sources technically does not mean you can share access with other devices or people.

Set Names, Insertion Points, and Priorities

Set naming conventions before merging: provider names should be unique, group names should remain stable, and node names should not conflict across sources. References use names; don't expect the client to distinguish sources automatically when displayed names are identical. If you need prefixes or renamed nodes, use a mechanism explicitly supported by the client or core, then test that filters still match the renamed nodes.

Local rules typically include priority exceptions and a catch-all selection. Internal domains that must take priority go before broad rules; the final MATCH should only serve as a fallback. Some merge mechanisms append local rules after the subscription rules. If the subscription already has MATCH, appended rules will never run. Change the merge method or explicitly rebuild the rule order instead of adding more similar rules at the end.

Recheck Behavior After Subscription Updates

After an update, check three things: whether the source loaded, whether group references still exist, and whether priority rules are still in the expected position. New subscription fields may be lost if an older override replaces the whole field. A locally saved group selection may also refer to a node that no longer exists. To find conflicts quickly, first disable personal overrides and confirm the original subscription works, then re-enable them one at a time.

If the client doesn't show the final configuration, at least keep the load logs, node list, and rule records for key connections. When restoring an old snapshot, remember that node credentials may have expired; a configuration loading successfully doesn't mean old nodes still work. For routine use, follow the import and connection steps in the Quick Start Guide. This section explains why merged results need to be checked after updates; it doesn't mean you must edit files manually every time you connect.

08 · External Controller and Ongoing Maintenance

The Controller API Is Not a Proxy Port

external-controller exposes the core's management API. A dashboard can use it to read status, switch policies, and perform administrative actions. It is separate from the mixed proxy port that accepts HTTP and SOCKS requests, and from the DNS listening port. Pointing a dashboard at the proxy port won't give it management access; using the controller port as a network proxy won't route traffic correctly either.

The controller can affect network behavior, so it should bind to a loopback address by default and allow access only from the local machine. For management from other devices, define the access boundary first, then consider the listening address, authentication, transport security, and firewall rules. Don't expose the API on every network interface just to open a dashboard from your phone, relying on an easy-to-guess example password. A leaked controller can do more than reveal status; it may also allow runtime selections to be changed.

Local Dashboard and Authentication

The snippet below shows a loopback listener and a local dashboard directory. your-password is an explicit teaching example; replace it with a strong, randomly generated secret before use. Don't post the real value in public support threads. external-ui points to a directory containing the prepared static dashboard files; setting the field alone won't make a working dashboard appear if those files aren't there.

external-controller: 127.0.0.1:9090
secret: "your-password"
external-ui: ./ui

If the client already includes a dashboard and controller settings, use its built-in controls to avoid conflicts between local overrides and interface settings. To test the management API manually, send a request from a trusted local terminal. The command below prompts for the secret rather than putting it in your shell history, then clears the variable from the current terminal when done.

read -r -s -p "Controller API secret: " MIHOMO_SECRET
printf '\n'
curl --fail --silent --show-error \
  -H "Authorization: Bearer $MIHOMO_SECRET" \
  http://127.0.0.1:9090/configs
unset MIHOMO_SECRET

This command is for Bash. Other terminals should use their equivalent secure input method. A successful request only confirms that the current terminal can reach the controller API; it doesn't guarantee the browser dashboard can do the same. Browsers are also subject to page origin, mixed content, cross-origin policies, and network address constraints. Check API connectivity and page access separately.

Confirm What the Address Means Before Remote Access

In a dashboard page, 127.0.0.1 refers to the device running the browser, not the remote host running the core. If you open the dashboard from another computer but leave the loopback address in place, the browser will try to connect to itself. A safer approach to remote management is a controlled encrypted tunnel or a reverse proxy with authentication and access restrictions, while keeping the core's controller bound to the local interface.

With a reverse proxy, check both regular HTTP requests and WebSocket connections; connection lists and logs may depend on an ongoing connection. A page that loads but doesn't update status may indicate that the proxy isn't forwarding upgrade headers, authentication doesn't match, or the browser is blocking the connection. Restrict cross-origin access to the page origins you actually need; don't open it up indiscriminately just to silence an error.

Static dashboard files also need maintenance. Use a known source for updates, save the working files and configuration before upgrading, then test login, policy switching, and log connections afterward. If the controller API works but the updated dashboard doesn't, roll back the dashboard files first rather than immediately changing the entire core configuration. If the client manages its built-in dashboard, follow its update process to avoid conflicts from manually replacing files.

Make Every Change Verifiable

After configuring, keep a brief record of which field changed, what you expected to happen, which new connection you used to test it, and which file to restore if it failed. For proxy groups, verify the selected outbound; for rule providers, verify match order; for DNS, verify the query path; for TUN, verify traffic entry and routes; and for the dashboard, verify authentication and access scope. This is more useful for long-term maintenance than saving piles of configuration screenshots from unknown sources.

When something goes wrong, troubleshoot in the same order: confirm that the configuration loaded, then that traffic reaches the core, and then check DNS, rules, and the outbound. A disconnected dashboard doesn't automatically mean the node has failed, and a page that won't load isn't a reason to change the controller API. For symptom-based help, visit the Help Center. To switch clients, compare platform options on the downloads page. The goal is to give each layer a clear job and make every change explainable, testable, and reversible.