Advanced Setup / Mihomo Configuration Guide

Advanced Clash Proxy Group,
DNS & TUN Configuration

From traffic matching to configuration maintenance, work through seven topics one layer at a time. Keep a working configuration and change one layer per test.

For installation, subscription imports, and enabling the system proxy, follow the Getting Started guide to connect. This page skips the basics and explains the proxy groups, DNS paths, and traffic-routing boundaries behind that connection. It’s for configurations that already work and need fine-tuning.

Proxy Groups & Rules DNS & Network Stack Overrides & Dashboards

Proxy Group Types and Examples

Start by distinguishing proxies, proxy groups, and rules. A proxy defines an actual connection; a proxy group chooses among available outbound connections; rules send traffic to a proxy group. Putting proxy names directly into many rules may seem simple at first, but it becomes hard to maintain: every rule must be updated when a proxy is renamed. A more maintainable setup points rules to groups with stable purposes, then swaps proxies within those groups. Names referenced in a configuration must match exactly; changes to spacing, capitalization, or punctuation can break a reference.

Select, URL-Test, and Failover Groups

select creates a group you choose manually, useful for a general or service-specific outbound group. It can contain proxies or other groups. url-test periodically checks an address for availability and response time, then selects an outbound based on the results. It works well when the candidate proxies are comparable. fallback prioritizes candidate order: it uses the first available outbound and moves to the next only if that one fails. It doesn’t reorder proxies by latency, so it’s for defined primary and backup routes, not a replacement for URL testing.

load-balance distributes different connections across outbounds according to its configured strategy; it doesn’t combine their speeds for a single download. Services that require a login session, a stable outbound, or a consistent region may trigger extra verification if the outbound keeps changing. Test with a manual group first, then decide whether load balancing is appropriate. Proxy latency tests only measure the test address, so they can’t prove that streaming, code repositories, or games will be faster. Verify with the actual service, too.

TypeHow it selectsCommon use
selectUser selectionPrimary outbound, service groups
url-testPeriodic test resultsAutomatically choosing among similar routes
fallbackCandidate order and availabilityPrimary/backup failover
load-balanceConnection distribution strategyServices that allow multiple outbounds

Build a Two-Layer Structure You Can Inspect

This structure separates manual selection from automatic checks. “Subscription Nodes” must be a provider already defined under proxy-providers, with at least one working node. Add “Manual Select” to the automatic group, then switch to a specific exit in the panel if something goes wrong. Don’t append the same example twice. If proxy-groups already exists, add these entries to its list under the existing top-level key.

proxy-groups:
  - name: Auto Select
    type: url-test
    use:
      - Subscription Nodes
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80
    lazy: true

  - name: Manual Select
    type: select
    proxies:
      - Auto Select
      - DIRECT
    use:
      - Subscription Nodes

interval is measured in seconds and sets the test interval; tolerance is measured in milliseconds and helps avoid switching over small fluctuations. lazy can reduce unnecessary tests while a group isn’t in use, though provider health-check settings also affect testing. Avoid setting both group tests and subscription health checks to very short intervals, especially on mobile networks, where frequent tests use more battery and data. First check whether the issue actually calls for a shorter interval.

Check References, Loops, and Session Stability

Keep nested proxy group references one-way: for example, a service group points to a primary group, which points to an automatic group, which finally points to proxies. Don’t make two groups reference each other or create a chain that leads back to itself. To troubleshoot an error, follow references downward from the affected group and check whether each name exists, the provider loaded, and any filters excluded all proxies. An empty group often means upstream proxies were filtered out, not that a rule is wrong; repeatedly editing rules won’t fix it.

Changing a proxy group usually affects new connections; existing long-lived connections may not move immediately. For a clean test, close old connections in the test app and make a new request. If needed, close only the relevant connection instead of restarting the whole device. Keep login-based services on a stable service group to avoid outbound changes as test results fluctuate. To understand how rules differ from global mode switches, see the guide to the three proxy modes. Switching global mode doesn’t prove that proxy group references are correct.

Managing Rule Providers

Rule providers separate frequently updated domain or IP-range lists from the main configuration. The main config keeps rule order and outbound names; rule files maintain the matching entries. This makes it easier to update service domains without repeatedly editing every proxy group, and to track what changed in an update. Rule providers and proxy providers are different: a rule provider supplies match conditions, not usable proxy connections. A successful download also doesn’t mean the main rules list references those rules.

Choose a Behavior and File Format

behavior: domain is for domain lists and works well for managing similar sites together; ipcidr is for IP ranges; classical can include traditional rule types such as domain suffixes, keywords, and IP ranges. Choose based on the file’s actual contents, not its extension. The entry structure in the file must match the provider’s format and behavior. Reading entries with rule-type prefixes as a plain domain list can cause a parse error or produce matches you didn’t intend.

Validate the structure with a local rule file before enabling remote updates; this makes troubleshooting easier. The path ./rules/work.yaml is relative to the kernel’s working directory, not necessarily the GUI client’s install directory. For sandboxed or service-based clients, use the provided configuration directory to confirm the path and check that the kernel can read it. The main rules use the group name “Manual Select” from the previous section; update it here if your configuration uses a different name.

# Snippet for the main configuration
rule-providers:
  Worksites:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/work.yaml

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - RULE-SET,Worksites,Manual Select
  - GEOIP,LAN,DIRECT,no-resolve
  - MATCH,Manual Select
# Contents of the rules/work.yaml file
payload:
  - DOMAIN-SUFFIX,github.com
  - DOMAIN-SUFFIX,githubusercontent.com
  - DOMAIN-SUFFIX,gitlab.com

Set the Rule Order Before Scheduling Updates

Rules are generally evaluated from top to bottom, and processing stops at the first match. Put specific exceptions before broad rules and keep the fallback MATCH at the end; otherwise, later rules never run. If a domain appears in two rule sets, the more specific one isn’t automatically chosen—the order of references decides. Before changing rules, note the matched rule, group, and outbound in the connection details. Then move one rule and compare the result; don’t reorder the entire list and check only whether a website opens.

To switch to a remote provider, set its type to http, then configure the source url, local cache path, and update interval interval. Use a rule URL whose contents and maintenance practices you’ve verified; don’t assume every online list is trustworthy. Give each provider its own cache path to prevent updates from overwriting each other. Set the interval to match how often the source changes; hourly or daily updates are usually more appropriate than repeated fetches. During troubleshooting, trigger a manual update if needed.

Remote downloads can also create a startup dependency: if fetching a rule file requires a proxy, but proxy selection depends on that rule set, the first startup can get stuck in a loop. Specify an already working outbound for the download or save a rule cache in advance, then check whether a cold start still succeeds. Don’t treat “configuration loaded” as proof that the provider is ready. Remote rules may still be downloading or the core may still be using an old cache, so check the provider’s update time and error messages.

IP Rules and Rule Fallbacks

no-resolve is for cases where you don’t want an IP rule to trigger a DNS lookup just to check an address. It doesn’t make all traffic bypass DNS. If a connection already has a destination IP, an IP rule may still match; if only a domain is known and there’s no IP, a rule with this option may be skipped. Before adding it to a broad rule, decide which later rule will handle the connection. Set up explicit direct routes for local networks, private addresses, and self-hosted services rather than relying only on a final proxy fallback.

If a rule update breaks some traffic, pause updates, restore the previous rule file, and compare the exact additions and removals. Check whether a domain was added to a higher-priority category, an IP range was widened, or the fallback outbound changed. If the file loads but never matches, check whether the connection retains its domain, sniffing works, and the app uses the core’s traffic path. For common issues with rule mode, see the FAQ. Keep the smallest rule set that reproduces the issue instead of rewriting the entire configuration.

DNS Configuration

To troubleshoot DNS, map the lookup path: where the app sends queries, whether they enter the core, which upstream the core uses, and which outbound carries those requests. A website loading in a browser proves only that one access path works; it doesn’t prove the system, app-level encrypted, and core DNS paths are all the same. With TUN enabled, queries previously handled by the router may instead be handled by the client. Running several tools that force DNS resolution at once makes the results harder to interpret.

Distinguish the Listener, Upstream, and Bootstrap Resolver

listen is where the core receives DNS queries; it isn’t an upstream server address. Binding to a loopback address is suitable for local use. Binding to a LAN address also requires attention to firewall rules and access scope. nameserver defines the upstream for ordinary queries; default-nameserver resolves the upstream’s own hostname, solving the chicken-and-egg problem of needing to resolve a DNS server before querying it. Using a numeric address for bootstrap can avoid that loop, but make sure the server is reachable from your network.

Use this as a starting point for troubleshooting: listen on a non-privileged local port, use an encrypted upstream, and route a specific domain suffix to a designated resolver. This won’t change system DNS or route every app’s queries by itself. After merging it, use the client’s DNS interception settings or configure TUN as described in the next section to send queries to the core. If the client already manages the listener port, don’t blindly set the same port; it could cause a binding conflict or create two competing configurations.

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:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "+.example.org":
      - 223.5.5.5

Route Domains to Specific Resolvers Instead of Stacking Upstreams

nameserver-policy is useful for corporate networks, self-hosted domains, and services that depend on a specific DNS path. Corporate domains need a resolver that can answer internal records; sending those queries to a public resolver usually returns no result or the wrong address. example.org in this example demonstrates suffix matching; it isn’t a real service that requires special routing. Confirm which resolver should handle the domain before replacing it with a domain you own or are authorized to access.

Adding more upstreams doesn’t automatically make DNS more reliable. Different upstreams may return content delivery addresses for different regions or use different caches, so mixing their results can make access inconsistent. If you use fallback, understand its filters and what triggers fallback; don’t assume it’s simply a list of backups used when the primary resolver times out. Start with one observable path and record lookup time, returned addresses, and actual service behavior. Add more routing strategies only after confirming the issue is at the DNS layer.

When DNS requests need to follow routing rules, respect-rules can help control their path. You’ll also need a clear resolution source for proxy server hostnames, such as proxy-server-nameserver. Otherwise, resolving the proxy address may require connecting through the proxy, while connecting through the proxy requires resolving its address—a loop. Check the core’s documentation and runtime logs for feature support. A DNS toggle in a GUI client may generate additional configuration, so don’t rely on a text snippet alone.

Check Caching, IPv6, and App-Level DNS

Test in three stages: query the core’s listener directly, test the system’s default resolver, then test the actual app. For example, use a tool that lets you specify a server and port: dig @127.0.0.1 -p 1053 example.org. If the first stage works but the second doesn’t, check system settings and the DNS interception path. If both work but the browser behaves differently, check secure DNS, the app’s proxy settings, and its cache. After changing the configuration, start a new test connection so an existing connection doesn’t hide the change.

Disabling IPv6 answers in the core’s DNS doesn’t stop the operating system from using IPv6 altogether. Apps may still use cached results, another resolver, or connect directly to an IPv6 address. Conversely, enabling IPv6 and receiving an AAAA record doesn’t prove the route works; check that the device, proxy outbound, and destination service all support it. If the issue occurs only on some networks, test IPv4 and IPv6 separately instead of repeatedly changing every DNS setting. Record the original system network settings before changing them so you can restore them.

If DNS changes cause intermittent failures, first check upstream reachability, listener conflicts, and whether queries actually reach the core. Clear caches only after that. Caching is useful; clearing it repeatedly adds more queries and can hide startup dependency issues. Public, corporate, and home networks may restrict different DNS protocols, so test each network separately. One successful lookup doesn’t prove every scenario is fixed, and an upstream address shouldn’t be treated as a permanent answer.

TUN and Fake-IP

TUN uses a virtual network interface to capture traffic covered by its routing rules, which helps with apps that ignore the system proxy. Fake-IP maps domains to virtual addresses so the core can recover domain information for later connections. They’re often used together, but they’re separate features. A working system proxy doesn’t prove TUN permissions or routes are correct. Seeing a virtual address doesn’t prove the connection reached a remote proxy. Check traffic capture, domain mapping, rule matching, and the final outbound separately.

Enable TUN in Order: Traffic Capture, Routing, DNS

First confirm that subscriptions and proxies work in the existing system proxy mode. Then disable other tools that modify routes and enable TUN. Desktop clients may need a service, administrator privileges, or a system network extension; mobile clients typically use the system VPN interface to capture traffic. The setup differs by platform, so don’t copy desktop permission steps onto mobile. For a first setup, try the recommended Clash Plus download, follow your system’s authorization steps, and confirm that the client uses a core that supports these fields.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"

auto-route lets the core add the routes it needs; auto-detect-interface helps identify the external interface and avoid sending the proxy’s own connections back through TUN. stack selects the network stack implementation; available options and their suitability depend on system support, so no single value is best for every device. The example uses mixed as a starting point. If startup logs report it as unsupported, follow the client’s documentation instead of changing DNS and rules at the same time.

Understand Virtual Addresses and DNS Hijacking Scope

Fake-IP returns an address for local mapping, not the destination website’s real public IP. So an unusual-looking lookup result alone doesn’t mean the setup failed. Check whether access succeeds and whether the connection details show the original domain. For LAN discovery, certain connected devices, or apps that need real addresses, add the relevant domains to fake-ip-filter so they resolve to real addresses. Filtering changes the kind of address returned; it doesn’t automatically route traffic directly. Add a suitable routing rule if direct access is needed.

dns-hijack with any:53 applies to traditional DNS requests that enter TUN and meet its conditions; it doesn’t capture all DNS traffic. Apps’ built-in DNS over HTTPS usually uses other ports, so this setting won’t detect it directly. If an app bypasses the core for DNS, the core may see only a destination address, and domain rules may depend on sniffing or other conditions to match. Identify the DNS protocol and actual traffic path first, then decide whether to change the app settings. Don’t use broader routing rules to mask differences in DNS paths.

PlatformCheck firstThen check
WindowsService mode, permissions, and virtual interfaceRoutes, firewall, and other VPNs
macOSClient permissions and system authorizationDefault interface and routes after network changes
LinuxTUN device and network management permissionsPolicy routing and DNS service conflicts
MobileSystem VPN authorizationBackground restrictions and conflicts with other VPNs

Check LAN Access and Stale Routes

After enabling TUN, test public internet access first, then your router’s admin page, printers, and corporate intranet. If only LAN access is affected, check direct-connection rules and route exclusions before switching proxies. Corporate VPNs may add private subnets and DNS settings; if they run alongside TUN auto-routing, define which one handles each address range. Keep route exclusions as narrow as needed. Excluding an overly broad range can bypass the core for traffic that should use a proxy, restoring one service while introducing new routing problems.

If all connections fail, disable TUN first and test with the system proxy. If the system proxy works, the proxy itself may be fine; check TUN initialization logs, default outbound detection, and route installation. A normal client shutdown usually removes the state it created. If the network still doesn’t recover after a crash, use the client’s repair tools to check services and routes, then restart the network if needed. Don’t delete routes in bulk without understanding the routing table, especially routes installed by a corporate network.

Fake-IP mappings and app DNS caches have their own lifecycles. After the core restarts, an app using an old virtual address may briefly fail to connect. Have it resolve the domain again before deciding whether to clear related caches. Background behavior on mobile can also affect reliability; see mobile background battery use and keep-alive trade-offs. Once everything works, record the normal interface, route, and DNS settings so you can compare them after a network change instead of troubleshooting from scratch.

Domain Sniffing

Domain rules need the core to know which domain a connection is for. Requests through a regular proxy entry often include the domain, but traffic entering through TUN may contain only a destination IP—especially when an app uses its own resolver, a cached result, or a direct IP address. Domain sniffing tries to recover the domain from protocol information at the start of a connection, such as the HTTP Host header or the server name in a TLS handshake. It fills an information gap; it doesn’t replace DNS or decrypt all app traffic.

Confirm the Domain Is Missing Before Enabling Sniffing

Start troubleshooting with the connection details. If the destination already shows a domain and the right rule matches, you don’t need to enable extra options just to make the configuration look complete. If it shows only an IP address, first check whether DNS reaches the core and whether the Fake-IP mapping still exists; then consider sniffing. Sniffing can change which rules match: connections previously routed by IP may gain domain-based matches. Before enabling it, compare a few known services and record the rules and outbounds before and after.

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

sniff specifies which protocols and ports to try to identify; it doesn’t open firewall ports. Include only the ranges you need so it’s clear which connections are processed. force-dns-mapping can extend sniffing to certain DNS-mapping scenarios; it doesn’t send every DNS request to the core. parse-pure-ip applies to traffic that connects directly to an IP address. The example leaves it disabled to avoid applying broader domain inference to connections with an explicit IP destination.

Distinguish Domain Matching from Destination Rewriting

override-destination controls whether a sniffed domain replaces the connection’s destination. Leave it off initially so you can see whether sniffing adds information for routing decisions without also changing the connection target. A service’s handshake name isn’t always interchangeable with its actual destination, particularly with self-hosted entry points, shared addresses, or special forwarding setups. If enabling it causes certificate errors, resets, or app failures, investigate destination rewriting as a separate variable instead of assuming the proxy is unavailable.

If a domain shouldn’t be sniffed, add it as a specific exception under skip-domain. Base exceptions on evidence from an actual issue, not a long generic list copied from the internet. Before adding one, repeat the test and record the domain, actual address, and matching rule shown for the connection. If disabling sniffing restores access, keep investigating whether protocol detection, destination rewriting, or rule order caused the issue. Understanding the cause helps avoid relying on ever-broader exclusions to keep things working.

Know the Limits of Encrypted Protocols

TLS sniffing relies on information visible during the handshake. With mechanisms such as encrypted client hello, it can’t guarantee recovery of the actual service domain. QUIC detection also depends on the protocol, implementation, and visible packet data; listing a protocol doesn’t mean every connection can be identified. For traffic whose domain can’t be recovered, use suitable IP rules or a fallback rather than expanding the port range indefinitely. If an app offers its own proxy settings, routing it through a proxy entry that carries the domain may be simpler than adding more sniffing rules.

Don’t treat sniffed information as app authentication. The host information in a connection is only a clue in that protocol context; it doesn’t prove which user made the request or provide a security boundary between tenants. Use separate network and identity controls for shared outbounds, internal authorization, and access control. In environments that require strict destination restrictions, have an administrator define verifiable rules. Domain sniffing alone can’t decide whether a connection is allowed, and a detected domain isn’t authorization.

For testing, keep three sample cases: a website using the core’s DNS, an app using its own resolver, and a service connecting directly by IP. For each, check the destination, matched rule, and final outbound—not just whether it opens. If enabling sniffing adds latency, test with just one protocol at a time, then restore options one by one. Raise log verbosity only enough to pinpoint the issue, then return it to the normal level. This avoids excessive connection logging and sharing logs that may contain browsing records.

Local Overrides and Multiple Subscriptions

Remote subscriptions update periodically, so editing a downloaded configuration directly can mean losing changes at the next refresh. Local overrides keep your preferred ports, DNS, rules, and proxy groups in a separately maintained layer while the upstream source continues to update proxies. Clients may call this overrides, merging, extended configuration, or script processing, and the underlying behavior varies. Before you start, find out which layer is being modified: the original subscription, the client’s saved configuration, or the final configuration passed to the core. These may all differ.

Check Merge Order and List Behavior First

Scalar fields are usually straightforward: for example, the last written mode replaces the earlier value. Lists may be appended, prepended, or replaced entirely; objects may be shallow- or deep-merged. Don’t assume that two clients behave the same just because both call the feature “merge.” Test a single harmless field in a local copy, preview the final configuration, and verify the result before adding DNS or rules. If the client has no preview, inspect the exported runtime config or startup logs. Remove subscription URLs and proxy credentials before sharing anything.

Pay particular attention to how rules are handled. If an override appends custom rules after an existing MATCH, they may never run. If it replaces the list, existing LAN and service exceptions may disappear. The same applies to proxy groups: replacing them all can break names referenced by upstream rules. List the stable group names you need to retain and specify where custom rules should go. Don’t try to simulate merging with duplicate YAML top-level keys; parsers don’t handle duplicate keys consistently.

Manage Multiple Subscriptions with Providers

You don’t need to concatenate several complete configurations to use multiple subscriptions. A more maintainable approach is to define each source as a separate proxy provider, then keep proxy groups, rules, and DNS in one main configuration. The example below uses two local proxy files; each must contain a valid proxies list, not an arbitrary complete client configuration. Paths are relative to the working directory. If you already have provider health checks, adjust them to your needs to avoid layering overly frequent checks on top of group tests.

proxy-providers:
  Route A:
    type: file
    path: ./providers/a.yaml
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 900
  Route B:
    type: file
    path: ./providers/b.yaml
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 900

proxy-groups:
  - name: Multi-Subscription Outbound
    type: select
    use:
      - Route A
      - Route B

To use remote providers, use valid subscription sources you’re authorized to access, with a separate cache path and update interval for each. Subscription URLs often contain access credentials; don’t put them in public repositories, screenshots, or support posts. Check the format of the upstream response, too: a URL meant for importing a complete configuration may not work as a provider file. If you get an error about a missing proxy list, check the response contents and provider type before changing individual proxy protocol fields. The issue may be in the top-level data structure.

If different sources use the same proxy names, dashboard selections and logs become harder to interpret, and name conflicts may occur. Prefer the name-prefix or suffix feature supported by your client or core to give each source a stable identifier. If you use a conversion script, run it on a copy first and inspect the output. Filters should reflect the intended source, not just region keywords, or an upstream rename could leave a group with no proxies. After merging, disable each source in turn to confirm that the other can handle the expected fallback on its own.

Verify the Runtime Configuration, Not Just the Editor

After each change, validate the configuration, reload it, and check the logs. If a Mihomo executable is available on your device, run the command below from the correct working directory. It checks file structure and references; it can’t prove that remote proxies or rule sources are reachable. GUI client users can use the built-in validation option instead of starting a second core process. Two processes can compete for ports and routes, creating problems that weren’t there before.

mihomo -t -f ./config.yaml

When recording a rollback point, save the original configuration, local overrides, and a change summary with sensitive information removed. Keep proxy credentials in a secure location; don’t include them in troubleshooting materials. After a subscription refresh, check the final rule order, provider status, and proxy count in each group, especially if the upstream changed group names or the default mode. For the recommended order of first-install settings, see the initial setup checklist. Once the configuration is stable, minimize automatic rewrite layers; each requirement should have one clear owner to make troubleshooting more direct.

External Dashboard

An external dashboard uses the core’s control API to read status, switch proxy groups, view connections, and manage providers. It isn’t a proxy entry, and a successful dashboard connection doesn’t automatically route apps through a proxy. Keep these three addresses distinct: the app’s proxy port, the DNS listener port, and the control address used by the dashboard. If the dashboard opens but shows no connections, confirm it’s connected to the core handling your traffic—not a leftover service, another config, or a second instance on the same device.

Bind to Localhost by Default

external-controller sets the control API’s listening address. For a personal desktop, bind to a loopback address so the API is reachable only on the local device. external-ui points to the directory containing the dashboard’s static files; make sure it exists and its location relative to the core’s working directory is clear. This snippet demonstrates a local listener and static directory only; it doesn’t include credentials. If the client already creates a control address and password, use its management settings rather than clearing existing authentication through an override.

external-controller: 127.0.0.1:9090
external-ui: ./ui

Dashboard authentication is controlled in part by settings such as secret. For a real deployment, use a strong password that you generate and store securely. Don’t include it in shareable dashboard links, screenshots, or public configs. Binding to localhost doesn’t make authentication unnecessary: account for other local programs and browser-based network requests, too. For a web-hosted dashboard, also consider browser restrictions on cross-origin requests, mixed content, and local network access. A page loading successfully doesn’t mean it can reach the control API.

Troubleshoot in This Order: Network, Authentication, Instance

If the connection fails, first make sure the core is running and the listening port isn’t in use, then check the protocol, address, and port configured in the dashboard. A connection refused error usually points to a listener or firewall issue; an unauthorized response points to authentication. If the dashboard can read status but shows the wrong groups, it may be connected to a different instance. Don’t switch to listening on every interface just to get it connected, and don’t disable authentication as a permanent fix. Establish a minimal working connection locally, then expand access one layer at a time.

To manage the core from another device, prefer a secured tunnel or an existing management network before changing the listener. Binding directly to 0.0.0.0 can expose the API on multiple networks; the actual exposure depends on firewalls, routing, and port forwarding. The control API can switch outbounds and inspect connections, so don’t expose it directly to the public internet. If a reverse proxy is necessary, configure encryption, access controls, and authentication, and account for browser cross-origin settings. Adding a forwarding rule alone isn’t enough.

SymptomCheck firstHow to verify
Connection refusedCore status, listening address, and portCheck the service and port locally
UnauthorizedDashboard password and core authenticationRe-enter the password for the current instance
Groups don’t match the configurationIs the dashboard connected to another instance?Compare the runtime configuration and working directory
Page loads, but requests failCross-origin requests, mixed content, and network permissionsCheck browser request errors

Read Connection Details Before Making Changes

Read connection details in order: entry point, destination, matched rule, proxy group chain, and actual proxy. The entry point tells you whether traffic came through the system proxy or TUN; the destination shows whether the domain was retained; the rule explains why a group was chosen; the group chain shows how it selected a proxy. Seeing “Manual Select” doesn’t tell you the final outbound—follow the chain. A webpage may create multiple connections, so distinguish the main request from resource requests by destination domain. One connection doesn’t represent the routing for the whole page.

Dashboard actions such as switching groups and reloading a configuration have different effects. Switching a group mainly changes later selections; reloading may update rules and group structure; closing a connection interrupts an active session. Record the current state, then act only on the connection you’re troubleshooting so you don’t also interrupt file transfers, remote terminals, or work calls. For a failed rule provider update, check download and parse logs; for an unavailable proxy, check the outbound. If a local app doesn’t appear in the connection list, check traffic capture at the entry point instead of repeatedly testing proxies in the dashboard.

Use a short maintenance cycle: save the current configuration, change one topic, validate the syntax, reload, check logs, then reconnect a known app to test. When testing on another network, check DNS and the default interface; after updating multiple subscriptions, recheck references and caches. Sharing a proxy on your LAN and exposing the control API are separate tasks. To let other devices use the proxy, see the mixed-port and allow-lan configuration guide; don’t enter the control port in a phone’s proxy settings. If you’re still stuck, consult the troubleshooting FAQ with a minimal, redacted configuration and reproducible steps.