Skip to main content

Policy Groups

Policy groups are used to organize and manage multiple proxy nodes, determining which node to use based on different selection strategies. Policy groups can contain proxy servers, other policy groups, or built-in policies.

Supported policy group types: select (manual selection), auto_test (automatic latency test), fallback (failover), load_balance (load balancing), external (external resource), conditional (conditional selection).

Built-in policies: DIRECT (direct connection), REJECT (reject connection).

Common Fields​

The following fields are common to all policy group types (except conditional):

  • name (string), required

    Policy group name, must be globally unique.

  • policies (string array), required

    List of sub-policies. Can be proxy server names, other policy group names, or built-in policies (DIRECT, REJECT).

  • flatten (bool), optional

    Expand all proxy nodes from nested policy groups. When set to true, nodes within sub-policy groups are fully expanded rather than showing only the policy group name. Often used in conjunction with filter.

  • filter (string), optional

    A regular expression filter that retains only nodes whose names match. Commonly used with flatten to filter specific nodes from subscriptions, e.g., (?i)香港|HK.

  • block_quic (bool), optional

    Block the QUIC protocol. When set to true, connections using this policy group will not use the QUIC/HTTP3 protocol.

  • icon (string), optional

    Icon, supports SF Symbols names or icon URLs.

  • hidden (bool), optional

    Whether to hide this policy group in the UI.

  • prev_hop (string), optional

    Previous hop proxy, used to build proxy chains. Traffic path: local device → previous hop proxy → current node → destination.

Manual Selection​

The user manually selects which sub-policy to use.

Uses only the common fields, no additional fields.

- select:
    name: "Manual Selection"
    policies:
      - HK Node
      - JP Node
      - Auto Select
    icon: globe

Auto Test​

Periodically tests the latency of all sub-policies and automatically selects the node with the lowest latency. When a node with lower latency is detected, it decides whether to switch based on tolerance.

In addition to the common fields, the following fields are also supported:

  • interval (integer), optional

    Latency test interval in seconds, default 600. Set to 0 or a negative value to disable automatic latency testing.

  • tolerance (integer), optional

    Switch tolerance in milliseconds, default 100. A switch occurs only when the new node's latency is faster than the current node by more than this value, preventing frequent switches when latencies are similar.

  • timeout (integer), optional

    Timeout for a single node's latency test in seconds, default 5, maximum 60.

- auto_test:
    name: "Auto Select"
    policies:
      - HK Node
      - JP Node
    interval: 600
    tolerance: 100
    timeout: 5

Fallback​

Tries sub-policies in order and selects the first available node. When the current node becomes unavailable, it automatically switches to the next one; when a higher-priority node becomes available again, it automatically switches back.

In addition to the common fields, the following fields are also supported:

  • interval (integer), optional

    Health check interval in seconds, default 600. Set to 0 or a negative value to disable automatic health checks.

  • timeout (integer), optional

    Timeout for a single node's health check in seconds, default 5, maximum 60.

- fallback:
    name: "Fallback"
    policies:
      - Primary Node
      - Backup Node 1
      - Backup Node 2
    interval: 600

Load Balance​

Distributes traffic across multiple sub-policies. Connections to the same domain or IP are assigned to the same node, while different domains/IPs are distributed across different nodes.

Uses only the common fields, no additional fields.

- load_balance:
    name: "Load Balance"
    policies:
      - Node 1
      - Node 2
      - Node 3

External Resource​

Loads a list of proxy nodes from a remote URL, supporting airport subscription links. Multiple subscription URLs can be configured, and nodes from all subscriptions are merged.

info

External does not use the policies field; node sources are specified by urls. The flatten and filter fields from common fields do not apply either.

  • name (string), required

    Policy group name, must be globally unique.

  • type (string), required

    Selection strategy after loading nodes. Possible values: select, auto_test, fallback, load_balance.

  • urls (string array), required

    List of subscription URLs, supporting HTTP/HTTPS URLs or local file paths. Nodes from multiple subscriptions are merged.

  • filter (string), optional

    A regular expression filter that retains only nodes whose names match from the subscription (e.g., (?i)香港|HK).

  • interval (integer), optional

    Latency test / health check interval in seconds, only effective for auto_test and fallback types, default 600.

  • tolerance (integer), optional

    Switch tolerance in milliseconds, only effective for the auto_test type, default 100.

  • timeout (integer), optional

    Latency test / health check timeout in seconds, default 5, maximum 60.

  • update_interval (integer), optional

    Subscription update interval in seconds, default 86400 (24 hours). Set to 0 or a negative value to disable automatic updates.

  • block_quic (bool), optional

    Block the QUIC protocol.

  • icon (string), optional

    Icon, supports SF Symbols names or icon URLs.

  • hidden (bool), optional

    Whether to hide this policy group in the UI.

  • prev_hop (string), optional

    Previous hop proxy.

- external:
    name: "Subscription"
    type: auto_test
    urls:
      - "https://example.com/subscribe"
    filter: "(?i)香港|HK"
    interval: 600
    tolerance: 100
    update_interval: 86400

Subscription File Format​

Local or remote subscription files should return a set of proxy server configurations:

proxies:
  - trojan:
      name: HK Node
      server: hk.example.com
      port: 443
      password: password
      udp_relay: true
  - shadowsocks:
      name: JP Node
      server: jp.example.com
      port: 8388
      method: aes-256-gcm
      password: password

Conditional Selection​

Automatically selects a sub-policy based on the current network environment (Wi-Fi SSID, BSSID, cellular network type). Rules are matched in order, and the first matching policy is used; if none match, the default policy is used.

  • name (string), required

    Policy group name, must be globally unique.

  • rules (array), required

    List of matching rules, matched in order. Three rule types are supported:

    • ssid - Wi-Fi name matching, supports glob wildcards (e.g., Home-*, Office*)
    • bssid - Wi-Fi router MAC address matching, supports glob wildcards (e.g., aa:bb:cc:*)
    • cellular - Cellular network type matching, supports glob wildcards. Available values: NR (5G), NRNSA (5G NSA), LTE (4G), WCDMA, HSDPA, HSUPA, CDMA, eHRPD, EDGE, GPRS

    Each rule contains two fields: match (glob match pattern) and policy (the policy to use when matched).

  • default_policy (string), required

    Default policy, used when no rules match.

  • block_quic (bool), optional

    Block the QUIC protocol.

  • icon (string), optional

    Icon, supports SF Symbols names or icon URLs.

  • hidden (bool), optional

    Whether to hide this policy group in the UI.

  • prev_hop (string), optional

    Previous hop proxy.

- conditional:
    name: "Network Environment"
    rules:
      - ssid:
          match: "Home-*"
          policy: DIRECT
      - bssid:
          match: "aa:bb:cc:*"
          policy: HK Node
      - cellular:
          match: "LTE"
          policy: Auto Select
    default_policy: Manual Selection

Configuration Example​

policy_groups:
  # Manual selection: filter Hong Kong nodes from subscription
  - select:
      name: "HK Node"
      policies:
        - Subscription
      flatten: true
      filter: "(?i)香港|HK|Hong Kong"
      icon: globe

  # Auto test
  - auto_test:
      name: "Auto Select"
      policies:
        - HK Node
        - JP Node
      interval: 600
      tolerance: 100

  # Fallback
  - fallback:
      name: "Fallback"
      policies:
        - Primary Node
        - Backup Node
      interval: 600

  # Load balance
  - load_balance:
      name: "Load Balance"
      policies:
        - Node 1
        - Node 2

  # External resource: merge multiple subscriptions
  - external:
      name: "Subscription"
      type: auto_test
      urls:
        - "https://provider1.com/subscribe"
        - "https://provider2.com/subscribe"
      filter: "(?i)香港|日本|HK|JP"
      update_interval: 86400

  # Conditional policy group: switch based on network environment
  - conditional:
      name: "Network Environment"
      rules:
        - ssid:
            match: "Home-*"
            policy: DIRECT
        - cellular:
            match: "NR*"
            policy: Auto Select
      default_policy: HK Node