Clash: From Beginner to Advanced
Client Setup & Rule Configuration

1. Core Concepts: Core, Client & Configuration

Separate the interface from the engine

Clash clients and cores serve different roles. A client provides configuration management, policy selection, system proxy controls and logs. The core listens for incoming traffic, parses requests, matches rules and establishes outbound connections. mihomo is an actively developed core in this ecosystem and is often integrated into GUI clients. Similar-looking Clash interfaces don’t guarantee support for the same fields, the same underlying core or the same configuration behavior.

A useful way to understand a connection is to follow four steps: an app makes a request; the system or app sends it to a proxy entry point; the core decides what to do based on the configuration; and the request reaches its destination directly or through a proxy. One working webpage only confirms that this particular path works. Other apps may ignore the system proxy, and other domains may match different rules. When troubleshooting, check the entry point, rule match and outbound route—not just whether a master toggle is on.

What nodes, proxy groups and rules do

A node describes the protocol, server address, port and authentication details required for a proxy connection. A proxy group collects nodes or other outbound options under one reference, making it easier to select one manually or switch according to a defined strategy. A rule specifies how a type of request should be handled. Rules refer to proxy groups, which then select a node. Rules can also point directly to the built-in DIRECT or REJECT outbounds, for direct access or rejection, respectively.

A subscription is usually an updateable remote configuration source, but its contents can vary. Some subscriptions return a complete configuration with nodes, rules and proxy groups; others provide only nodes and rely on a client template for the rest. Treating a node list as a complete configuration can leave you without selectable proxy groups, or with nodes that no rules use. Identify the content type before importing it rather than repeatedly switching modes.

YAML files and the active configuration

Configurations are often saved as config.yaml. YAML uses indentation to define structure: keys at the same level must line up, list items use hyphens, and tabs cannot replace spaces. A space is usually required after a colon, and strings containing special characters are best quoted. A successful parse only confirms valid syntax; it doesn’t guarantee that proxy group references, file paths, network permissions or other runtime requirements are correct. After editing, check that the core accepts the configuration and review the rule match for an actual request.

A GUI client may store the original subscription, a template, override snippets and generated runtime files separately. The file you just edited on disk may not be the one the core is using, and the next subscription update may overwrite manual changes. Check the client’s configuration preview or active configuration entry point to confirm where each field comes from, and note whether a GUI toggle takes precedence. Merge examples into a managed override layer rather than blindly replacing the entire subscription.

Also distinguish the software from the network service. Installing a client doesn’t provide working servers, and open-source code doesn’t come with connection resources. Service availability, data limits and provider account status are separate concerns. Treat subscription contents as account credentials: don’t post them in public discussions, online conversion tools or screenshots. Before importing an unfamiliar configuration, inspect its remote resources, listening addresses and control interface.

2. Choose a Client: Platforms & Practical Limits

Start with your device, then compare client features

For a first installation, consider Clash Plus, then compare other clients based on your platform, desktop environment and existing preferences. Start by checking your operating system, processor architecture and installer format—not by comparing screenshots. Desktop clients are suited to configuration management and connection monitoring; mobile clients usually route traffic through the system VPN interface; and a standalone core on a server requires you to manage its configuration and process. These have different setup paths, so don’t assume the same permission steps apply to all of them.

Visit the downloads page to see the available clients and platform notes in one place. If you’re new, choose a maintained client that starts reliably and supports your device, then establish one basic connection before comparing extra features. Switching clients repeatedly also changes configuration merging, DNS defaults and traffic capture, making one issue look like several software problems and complicating cleanup of leftover proxy settings.

Client options by platform

On Windows, compare Clash Verge Rev, FlClash and Clash Nyanpasu; on macOS, compare Clash Verge Rev and FlClash. For Linux, start with Clash Verge Rev and FlClash, checking which package format matches your distribution. On Android, options include Clash Meta for Android, FlClash and Surfboard. Surfboard’s configuration format is not interchangeable with Clash YAML; follow its own import instructions. A shared subscription URL doesn’t guarantee that every client can parse it.

On iOS, start by checking Clash Plus in the App Store and confirming your device is supported. The product website is clashplus.io. A VPN indicator on a mobile device only shows that the relevant network interface is enabled; it doesn’t mean every destination is being proxied. Actual behavior depends on the client’s supported rules, exclusions and outbound configuration. Verify a specific app and destination rather than relying on the status-bar icon.

Maintenance status and migration

Clash for Windows and ClashX Meta are archived projects that are no longer maintained, so they’re not recommended as the default choice for a new device. Even if archived software launches, it may have limitations with permissions on newer systems, protocol support or configuration fields. To migrate, export your configuration sources and manual rules, back up the old setup, then import them into the new client. Don’t copy the entire application data directory: database formats, paths and encrypted storage may differ.

When comparing features, check each one against a specific need: does the client support your subscription format, preview the active configuration and provide a stable override mechanism? Does TUN require an extra service? Are logs easy to filter? A control available in one client doesn’t imply the same implementation on another platform. In particular, understand desktop system proxy settings, service mode and mobile VPN capture separately; identical labels don’t guarantee identical behavior.

Most desktop users don’t need to download the mihomo core separately. A client already manages core startup, configuration paths and some permissions; replacing the core manually can cause control interface incompatibilities or mismatched startup arguments. Running the core directly is a better fit for servers, routers or process-managed environments, where you’ll also be responsible for service management and network isolation. Once you’ve chosen a client, stick with it and its configuration source to keep the next stage reproducible.

3. Installation & Permissions: Set Up a Recoverable Environment

Note your current network settings before installing

Before installation, check whether other proxies, VPNs, traffic filters or security tools are already running. Note the current system proxy, existing VPN profiles and any required corporate network settings to avoid multiple programs changing the same settings. When migrating from an older client, disable its system proxy and TUN normally, then quit the process. Deleting the app alone may leave system proxy settings, services or virtual adapters behind, so don’t assume uninstalling restored your network.

Get installers from this site’s download page or the relevant project channel, and confirm the platform and architecture. Windows system architecture and processor type, macOS chip type, Android instruction set and Linux package format all determine which file you need. An archive that extracts successfully may still contain an app that can’t run. If you see an architecture mismatch, return to the downloads page and choose the right file; changing the extension or extracting it again won’t help. Keep a record of the download source for future updates and rollback.

Desktop: distinguish installation permissions from network permissions

On Windows, after the first launch, make sure the main interface and core are running before deciding whether to install an optional service component. System proxy settings are usually tied to the current user, while TUN and background services may require elevated permissions. Assess firewall prompts against the program path, network use and listening scope; don’t allow all inbound connections just to dismiss a prompt. For local use, prefer loopback listening and leave LAN access disabled.

On macOS, follow the installer instructions to move the app to the appropriate location, then address any specific first-launch prompts in System Settings. Network extensions, helper components, system proxy settings and Keychain permissions are separate; don’t treat every prompt as the same error. If the app keeps asking for permission, verify its installation location and check for another copy with the same name before launching an old version by mistake. See macOS network extension and Keychain permissions for details. Don’t disable system security wholesale.

On Linux, distinguish a successful package installation, a working GUI launch and network permissions for the core. Missing desktop dependencies may prevent the window from opening; insufficient permissions may affect only TUN; and whether apps honor the system proxy depends on the desktop environment. Install the package format specified for your distribution, then test a normal-permission launch first. If you need capability permissions or service mode, use the client’s supported approach rather than running the entire GUI as root by default.

Mobile: VPN permission and background operation

Android and iOS usually ask to add or enable a VPN configuration on the first connection. Confirm the prompt comes from the client you just installed, then grant permission. On Android, also check battery optimization, background activity and automatic cleanup settings. If the connection drops when the screen locks or stops updating after you switch apps, the OS may be restricting the process rather than the node being misconfigured. Test with the app in the foreground first, then grant only the background permissions you need.

Don’t enable several traffic capture methods at once on first launch. Import your configuration and use the client’s logs to confirm the core loads correctly; then enable the system proxy on desktop or follow the normal VPN connection flow on mobile. After testing, practice a clean shutdown: disable traffic capture, confirm the system proxy is restored, quit the client and verify direct access. Being able to stop the client and restore connectivity is essential before trying TUN or complex rules. Don’t test only how to turn it on.

4. Import a Subscription: Sources, Updates & Overrides

Know whether you have a URL or a file

Subscriptions are usually imported through one of three methods: a remote URL, a local file or pasted text. Use a remote URL for periodic updates, a local file for backups or static configurations, and pasted text for a quick test. Choose the import method that matches the content. Don’t use a documentation webpage as a subscription URL or paste YAML into a field that accepts only URLs. Subscription URLs may contain account credentials: store them securely and don’t share them or leave them on a public device.

Create a configuration in the client’s configuration manager, give it a recognizable name and import the content. Wait for the download and parsing to finish. Then set it as the active configuration; appearing in the list doesn’t mean the core has switched to it. Check that proxy groups appear, nodes are selectable and the logs report a successful load. If loading fails, start with the error line and field name. Fix the content format rather than repeatedly clicking Connect while the configuration is still inactive.

Tell download errors, parse errors and connection failures apart

A subscription download failure happens while fetching the configuration and may involve DNS resolution, account status, access restrictions or the subscription server’s response. A parse failure means content was received, but it might be a login page, an error page, a different client’s format or malformed YAML. A node connection failure occurs after the configuration loads and points to server reachability or authentication details. These happen at different stages: identify where the failure occurs before choosing how to troubleshoot it.

If the subscription returns a complete configuration, keep its default proxy groups and rules for the initial checks. If it returns nodes only, use a client-supported template or the provider’s instructions to complete the configuration; don’t combine it with an unfamiliar template at random. Template proxy group names must match the names used in rules, and nodes must be connected to the right groups. For errors such as “proxy not found,” check names, capitalization and merge order—not just whether nodes appear in the list.

Overrides and subscription updates

Put manual settings in an override or merge layer supported by the client whenever possible. Editing the downloaded subscription directly may be undone by the next update; editing a runtime file may be undone when the client restarts. Clients differ in whether they replace, append or prepend lists, so inspect the final rules, proxy-groups and dns values. Don’t assume that merge behavior in one client applies to another.

The following snippet shows top-level settings only, to illustrate that local preferences should be kept separate from node details. It contains no nodes or proxy groups and cannot establish a proxy connection on its own. If the client already manages these settings through its interface, prefer the relevant controls and check the configuration preview. Setting the same value both in the interface and in a file can cause one to overwrite the other on startup, making ports or modes seem to revert unexpectedly.

# Top-level settings snippet; merge with an existing complete configuration
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

Before updating a subscription, save the current working configuration and any important manual selections. After the update, compare proxy group names and node counts, and review the logs. A stale selection becoming unavailable doesn’t mean the entire subscription is broken. If a provider removes or renames a node, the client may revert to its default; choose an available outbound again and verify your usual destinations. Set automatic update intervals based on provider limits and actual needs—repeated refreshes won’t improve server quality.

If a subscription URL is reachable only through an existing proxy, use the client’s supported proxy-based update method or restore a working route first. Don’t leave all traffic in global mode just to update a subscription. When sharing a problem, provide only redacted error details, the import method and the configuration type—not the original URL. For a broader guide to subscription sources and errors, see subscription troubleshooting, then follow the steps for the stage where the error occurs.

5. Proxy Modes: Configure Traffic Entry and Routing Separately

Rule, Global and Direct control routing decisions

Rule mode chooses an outbound for each request according to the configuration and is suited to everyday use. Global mode sends requests that reach the core through the selected global policy. Direct mode sends those requests straight to their destinations. These modes control what the core does after receiving a request; they don’t ensure every app sends traffic to the core. Global mode therefore doesn’t capture all traffic on the device—some apps may still bypass the system proxy.

Use Rule mode for everyday traffic and compare Global mode briefly only when investigating a rule mismatch. If a destination works in Global mode but not Rule mode, check the matched rule and selected outbound instead of leaving Global mode on as a permanent fix. Direct mode also doesn’t mean the client is fully stopped: the core, listening ports or VPN interface may still be active. To fully restore normal network behavior, disable the relevant traffic capture entry point too.

System proxy: coverage depends on app support

A system proxy usually points proxy-aware apps to a local listening port. Browsers and some apps use this setting, but command-line tools, games and apps with their own network stack may ignore it. Some apps also have a separate proxy setting that must be configured in-app or through environment variables. If the browser works but another program doesn’t, first check whether it appears in the core’s connection list, then check its rule and node. Don’t mistake a missing entry point for a proxy server problem.

Environment variables affect only processes that read them, and an application’s own settings may override them. The command below sets a proxy for a single request in a Unix-like terminal, assuming the local mixed port matches the example value. In Windows PowerShell, call curl.exe explicitly if using this test. A successful request proves only that this command reached its destination through the specified entry point; it doesn’t show that other apps use the same settings.

curl --proxy http://127.0.0.1:7890 --head https://example.com

Port settings: listener address, type and conflicts

mixed-port provides HTTP and SOCKS entry points, while port and socks-port configure separate entry points. Use the port values in the active configuration; example numbers aren’t fixed defaults across clients. If the logs say an address is already in use, check for another client or an old core process before closing the conflicting program or changing the port. After changing it, update the system proxy and any manual settings in individual apps.

The listening address determines which devices can reach an entry point. For local use, keep LAN access disabled and check the actual bind scope. If you enable allow-lan, restrict access using the bind address, firewall and network settings; don’t expose an unprotected proxy entry point to the public internet. LAN devices should connect to the local network address of the device running the client, not its loopback address. Also account for network isolation and device sleep.

Verify the mode using connection logs

For a test, choose a specific destination, close any existing connection or send a fresh request, then check the connection list for its domain, matched rule, policy chain and outbound. Persistent connections, browser connection pools and caches can make a mode change appear delayed; existing connections may not be recreated immediately. Note the active mode and test time so you can find the corresponding log entry. For connection issues, follow the steps in connection troubleshooting.

Some clients allow the system proxy and TUN to run together, but when troubleshooting for the first time, keep just one clear entry point. Using both may route a request through an app proxy before capturing it with the virtual adapter, making the path harder to follow. First verify the configuration and outbound using the system proxy, then expand traffic coverage if needed in the next stage. Clear entry points, modes and test destinations make it possible to locate whether an issue comes from traffic capture, rule matching or the external network.

6. Rule Routing: Match Order & Proxy Groups

Rules are checked from top to bottom; the first match wins

Rules are generally checked from top to bottom, and a request is handled by the outbound specified by the first matching rule. Rules don’t vote or automatically favor the “most specific” match. Put explicit domain exceptions before broad rules, avoid letting a catch-all proxy rule override basic direct rules such as local network addresses, and keep the final MATCH rule at the end. A rule added below an earlier match may never be reached.

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix and its subdomains, and DOMAIN-KEYWORD matches domains containing a keyword. Keyword rules can match more than expected, so don’t use a short, broad term as a shortcut for an entire service. IP-CIDR matches an address range, GEOIP uses an IP geolocation database, and GEOSITE depends on domain classification data. The relevant database and usable rule tags must be available for these rules to load.

Define proxy groups before referencing them

Proxy group names are part of the configuration interface and must match exactly wherever a rule references them. The snippet below defines a manual selection group named Proxy containing only the built-in direct outbound, to demonstrate the structure and rule reference. It cannot proxy traffic as written. In practice, add node names already defined under proxies or connect a correctly configured provider. Don’t mistake the demo group’s DIRECT entry for a selected proxy node.

# Structure demo: Proxy currently contains only DIRECT
proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,github.com,Proxy
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,Proxy

select is for manual selection; url-test selects candidates based on probe results; fallback prioritizes keeping an outbound available in a defined order; and load-balance distributes connections according to its strategy. Automatic probes target a specified test URL: their results don’t represent every website or directly predict download throughput. Understand the candidate set and trigger conditions before enabling automatic selection. Avoid deeply nested groups that make the final outbound hard to trace.

Where domain rules and IP rules differ

Some IP rules need to resolve a domain first to determine the destination address. no-resolve prevents that rule from actively triggering resolution for its IP match, but it doesn’t mean DNS is no longer used anywhere in the request. If the request already includes an IP address, the rule can still match it. Whether domain information is available also depends on the app’s entry point, DNS mode and sniffing settings. If a domain rule doesn’t match, check whether the connection record actually includes a domain before adding more domain entries.

rule-providers can separate large rule collections from the main configuration, but the source, cache path, format and matching behavior must be set correctly. Domain sets, IP sets and classical rule formats aren’t interchangeable, and a RULE-SET reference must use the matching provider name. First verify routing with a few local rules, then add remote collections. If a remote update fails, check whether a usable cache exists and whether the active contents are what you expect.

Test individual destinations, not the number of rules

Before adding a rule, state the expected result: which domain or address, which group should handle it and why an exception is needed. After saving, create a fresh test connection and check the matched rule and final outbound. If the result is wrong, look for an earlier match and check whether the client appended override rules after the catch-all. More rules don’t necessarily mean more accurate routing; duplicates and overlapping entries make maintenance harder. Keep purpose comments and rollback notes instead of piling on rules.

For setups that route traffic in mainland China directly and proxy other destinations, see a practical guide to rule routing. Don’t treat geolocation databases as definitive indicators of business location: CDNs, shared infrastructure and cross-region services can produce edge cases. Use clear domain exceptions for essential services and verify both routing rules and DNS to keep the setup maintainable.

7. TUN & DNS: Expand Traffic Capture

Make sure the standard proxy entry point works first

TUN uses a virtual network interface to receive packets routed through it, making it useful for apps that ignore the system proxy. It changes how traffic reaches the core; it won’t fix a dead node, incorrect authentication or faulty rules. Before enabling it, verify a connection through a clear proxy entry point so you know the configuration and outbound work. If the basic route isn’t working yet, changing routes and DNS at the same time adds variables and makes the problem harder to isolate.

TUN implementation depends on the operating system, core capabilities and client permissions. Desktop setups may need a service component or administrator approval. Mobile systems usually provide similar traffic capture through their VPN interface, so don’t copy a desktop YAML snippet unchanged. If virtual adapter creation or route setup fails, check permissions and client service status first; switching nodes repeatedly won’t fix local interface initialization.

Routing and DNS interception do different jobs

auto-route sets relevant routes automatically, auto-detect-interface detects the outbound interface, and dns-hijack sends matching DNS requests to the built-in DNS handler. The following is a partial desktop mihomo configuration; merge it with valid outbound settings and make sure the client manages the required permissions. If the interface already provides TUN and DNS controls, check the generated configuration rather than maintaining two sets of settings that may overwrite each other.

# Desktop TUN / DNS snippet; confirm the client supports these fields first
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
  nameserver:
    - https://dns.alidns.com/dns-query

DNS overrides and what fake-ip means

DNS settings determine how domains are resolved and can affect rule matching and connection setup. In fake-ip mode, a domain is assigned an address for internal mapping; the core uses that mapping to recover the domain and handle the connection. It isn’t the destination website’s real server address. If an app bypasses the core and uses that address directly, or an old cache retains an expired mapping, that app may fail to connect. After changing DNS modes, create a fresh test connection and clear system or app caches if needed.

Some LAN services, device discovery features and apps that rely on real DNS results may need fake-ip-filter or a client-specific compatibility setting. Don’t add every domain to the filter as soon as something goes wrong, or change the entire address pool without a reason. Identify what fails, whether it’s on the LAN and whether only one app is affected, then add the narrowest possible exception. Filter behavior may also depend on the configuration mode, so check the core documentation and the active fields.

Intercepting standard DNS ports doesn’t capture all encrypted DNS. A browser or app may use its own DoH or DoT connection, and system-specific DNS settings can also change the route. First identify which component handles resolution, then decide whether to route it through the core or leave the app’s settings in place. Remote DNS servers also need a reachable route. If a resolver is specified by domain name, consider how that name gets resolved initially to avoid creating a resolution loop.

Troubleshoot routing, resolution and outbound in order

After enabling TUN, test a regular domain first, then an app that doesn’t normally honor the system proxy, and finally LAN devices and recovery from sleep. If something fails, check whether the connection reaches the core. No log entry? Check routes, exclusions and permissions. An entry with a DNS failure? Check DNS. A selected outbound with a connection failure? Check the node and destination. When finished, turn TUN off and confirm the network is restored so leftover routes aren’t mistaken for an ongoing service outage.

Other VPNs, container networks, virtual machines and corporate tunnels can conflict with TUN routes. Don’t delete unfamiliar system routes; stop the traffic capture you just enabled and compare behavior first. If needed, use the client’s route exclusion feature and note that excluded traffic bypasses the current core. TUN should fill gaps in traffic capture, not remove configuration boundaries. This stage is complete when you can explain which traffic is captured and which is excluded.

8. Maintenance: Logs, Backups & Updates

Correlate requests and errors by time

Good maintenance starts with reproducible records. When a problem occurs, note the time, network, destination domain, client mode and active policy selection, then send one clear test request. Interpret log errors in context: a connection timeout, DNS resolution failure, remote disconnect and configuration parse error occur at different stages. A screenshot of only the last line often misses the actual cause and can make routine retries look like a persistent failure.

Use a moderate log level for everyday use and increase detail temporarily when reproducing an issue. Detailed logs may include domains, addresses, process names and configuration information, so limit how long you keep them and who can see them. Restore your usual log level after testing to avoid recording more browsing details than necessary. For common errors, see how to diagnose Clash runtime logs. Focus on where the error occurred rather than searching for the error text alone.

Break speed tests into separate measurements

A successful connection doesn’t guarantee the expected speed. Slow access may be caused by the destination service, proxy server load, outbound route, local Wi-Fi or the app itself. First compare direct and proxied access on the same device, then compare different outbounds under the same configuration, and finally check local network conditions and other app traffic. A proxy group’s probe only reports the response from its test address; it doesn’t predict large-file throughput or represent an entire session.

Keep the destination, time and network conditions as consistent as possible. If you change nodes, DNS, TUN and rules at the same time, you won’t know which change helped. Compare one factor at a time using a layered approach to diagnosing slow speeds, and record useful findings. If only one website is affected, check its matched rule, CDN route and connection reuse before reinstalling the client or resetting every setting.

Back up both sources and overrides

A useful backup is more than a single YAML file. Record subscription sources, the client’s merge settings, manual rules, proxy group selections and any system traffic capture options you rely on. Keep sensitive information in a protected location, not in a public code repository or an untrusted shared folder. Make sure you can tell what each file is for, and create a new restore point before making changes. If you can’t tell which file was active, restoring it may simply restart the troubleshooting process.

Updating a client and updating a subscription are separate operations. A client update can change the interface, core and permission handling; a subscription update changes remote configuration content. Do them separately: update one, verify startup, configuration loading, usual destinations and LAN access, then update the other. A changed interface doesn’t prove the core was updated. Don’t manually replace files inside the app without checking compatibility. To roll back, use the original installation source and your saved configuration.

Network changes, sleep and clean shutdown

When switching from wired to Wi-Fi, from a home network to a mobile hotspot, or resuming from sleep, the outbound interface, DNS and routes may change. Check whether the client detected the new interface, then try stopping and re-enabling traffic capture normally. If only one type of network fails, compare its captive portal, access restrictions and other VPNs instead of deleting all local rules. On mobile, also make sure the OS hasn’t killed the background process.

Before quitting normally, disable the system proxy or VPN capture, wait for the app to confirm it has stopped, then exit. If a crash leaves the network unavailable, check whether the system still points to a stopped local proxy port and use the client’s recovery method for services or routes. Follow the same steps before uninstalling. The goal isn’t to keep the app running forever, but to understand how it affects the system network when it starts, stops or fails.

9. Advanced Setup: Reusable Configuration & Runtime Boundaries

Separate responsibilities instead of growing the main file

Once basic connectivity works, organize the configuration before adding advanced features. Manage remote node sources, policy selection, traffic rules and local environment settings separately: nodes change with subscriptions, groups define how to select them, rules define where traffic goes, and local overrides handle ports, DNS and traffic capture. This makes it easier to switch subscriptions without rewriting every rule and to identify environment-specific settings when migrating devices. Splitting files only helps if you understand how the client merges them.

proxy-providers and rule-providers manage proxy sources and rule sources, respectively; they aren’t interchangeable. Before adding either, confirm the content format, update path, cache location and reference names, and check what happens if the first download fails. Remote resources add startup dependencies, so avoid making every part of the base configuration depend on a proxy connection that hasn’t been established yet. A cached copy isn’t guaranteed to stay valid; keep a clear update and recovery path.

Understand the cost of nested strategies

Nested proxy groups can separate business-level choices from specific nodes, but too many layers hide the final outbound. Start with a clear manual group, then add automatic testing or failover only when there’s a practical need. For each new layer, check its candidates, test route and default selection. Automatic switching usually affects new connections and can’t guarantee existing sessions won’t be interrupted. Test long-lived apps in real use rather than relying on the group’s currently displayed name.

Review rule sets before relying on them. Third-party collections may have scopes, update schedules and classification logic that don’t fit your needs, and oversized sets can add startup and maintenance costs. Keep necessary local exceptions, decide whether they go before or after remote sets, then add categories gradually. For important destinations, document the expected outbound and how to verify it, so you don’t have to guess when a remote rule changes.

External control interface: expose only what you need

The external control interface lets clients and management tools read status, switch policies and update configuration. It has more authority than an ordinary proxy entry point. For local use, bind it to loopback; don’t expose it to the public internet just for convenience. The snippet below shows the structure of one top-level field, not an instruction to enable the interface manually. A GUI client may already manage the address and authentication; changing them directly can disconnect the interface or create a conflict, so check the client documentation first.

# Shows loopback binding only; does not replace authentication or access controls
external-controller: 127.0.0.1:9090

For management across devices, first design a protected access path with authentication, firewall rules and the narrowest necessary exposure; don’t just change the listening address. Proxy entry points, control interfaces and DNS listeners are separate services, so check their bind scopes and permissions individually. Never include control interface credentials in public examples, screenshots or issue reports. Loopback binding also doesn’t remove the need to trust apps and scripts on the local machine.

Moving from a desktop client to the standalone core

On servers and routers, you’re responsible for startup arguments, configuration paths, file permissions, log rotation and service recovery. Test a known configuration in a non-critical environment first, confirm paths and listening scope, then configure startup at boot. Don’t immediately replace the device’s default route on first launch—especially on a remotely managed machine—because a bad route change can drop your current session. Keep a separate recovery channel and test restarts, network changes and remote resource download failures.

Standalone core configurations may support a test mode for checking load conditions, but first confirm the options in the help output for the binary you’re using and understand what the test covers. Passing syntax and reference checks doesn’t prove that remote servers are reachable, routing permissions are sufficient or the system DNS path is correct. For production, verify the entry point, resolution, rule matching and outbound in turn. Don’t copy client-generated files to a server without accounting for relative paths, cache directories and platform differences.

Measure progress by results you can explain

By the end of this stage, you should be able to trace a specific request from its entry point through DNS resolution, rule matching and proxy group selection—and explain how to restore the original setup. Leave advanced options at their defaults unless you have a clear need; a longer configuration isn’t automatically better. For quick setup, return to the getting started guide. To investigate a specific issue, visit Troubleshooting. Add your test results to your maintenance notes and refine a configuration that fits your devices and network.