# Policy group

> Selection, URL test, fallback, load balance groups

[← Back to index](/llms.txt)

---

## Common parameters

# Common Policy Group Parameters

## `no-alert`

This parameter prevents notification displays when the policy group changes.

## `hidden`

This parameter conceals the group from the menu interface on Surge Mac and removes it from the policy selection interface on Surge iOS.


## Fallback

# Fallback Group

## Overview

A Fallback Group selects an available policy based on priority and availability. It tests availability by accessing a URL, similar to an automatic testing group, but focuses solely on availability rather than latency measurements. Policies listed first have higher priority.

**Example syntax:**
```
FallbackGroup = fallback, ProxySOCKS5, ProxySOCKS5TLS
```

## Temporary Override

Users can manually override automatic testing results:

- **Surge Mac:** Access the override option through the main menu within the corresponding group
- **Surge iOS:** Long-press the policy menu in the policy group view to find override options

## Configuration Parameters

**`interval`** (optional, default: 600 seconds)
Controls how long cached benchmark results remain valid before being discarded.

**`timeout`** (optional, default: 5 seconds)
Sets the maximum duration to wait for a policy response; policies exceeding this threshold are abandoned.


## Group

# Policy Group

A policy group may contain multiple policies. It can be a proxy policy, another policy group, or a built-in policy.

## Purpose

The existence of policy groups is to allow for flexible adjustment of the specific policies being used when proxy rules are applied, without the need to modify the rules themselves.

## Group Types

There are several group types available:
- `select` - Manual Selection Group
- `url-test` - Automatic Testing Group
- `fallback` - Fallback Group
- `load-balance` - Load Balance Group
- `subnet` - Subnet Group

Policy groups should be declared in section `[Proxy Group]`.


## Load balance

# Load Balance Group

A load-balancing group randomly selects a policy from the available sub-policies to use.

## Parameters

### `persistent`: Optional

When `persistent=true`, the same policy will be used for the same target hostname. This approach helps prevent triggering risk controls on the target site due to different egress IPs. However, a policy change may occur when availability changes.


## Policy including

# Policy Including

## Include External Policies

Policy groups can import policies from external files or URLs:

```
egroup = select, policy-path=proxies.txt
```

External files contain policy definitions matching the main profile format:

```
Proxy-A = https, example1.com, 443
Proxy-B = https, example2.com, 443
```

### Optional Parameters

**`update-interval`** — Specifies refresh timing in seconds, applicable only for URL-based sources.

**`policy-regex-filter`** — Filters policies by matching regex patterns against policy names.

**`external-policy-modifier`** — Adjusts parameters of imported policies. For example: `"test-url=http://apple.com/,tfo=true"`

**`external-policy-name-prefix`** — Prepends a prefix to imported policy names for easier identification when using multiple external groups.

## Include Existing Policies (iOS 4.12.0+, Mac 4.5.0+)

Reuse policies from the main configuration or other groups:

**`include-all-proxies`** — Set to `true` to include all proxy policies from the [Proxy] section, compatible with `policy-regex-filter`.

**`include-other-group`** — References policies from other groups using comma-separated names: `"group1,group2"`. Supports `policy-regex-filter` for selective inclusion.

### Usage Notes

- All three parameters (`include-all-proxies`, `include-other-group`, `policy-path`) can coexist in a single group
- `policy-regex-filter` applies universally across all three
- For order-dependent scenarios (like fallback groups), nest policy groups using `include-other-group`


## Select

# Manual Selection Group

## Overview

A Manual Selection Group allows users to actively choose which policy will be applied through the application interface.

## Syntax

```
SelectGroup = select, ProxyHTTP, ProxyHTTPS, DIRECT, REJECT
```

## Usage by Platform

**Surge iOS**: Use the Widget feature to quickly switch policies for manual selection groups.

**Surge Mac**: Access policy switching through the menubar menu.

## Key Feature

This group type enables dynamic, user-controlled policy selection rather than automatic routing decisions. Users can change the active policy at any time based on their immediate needs.


## Subnet

# Subnet Group

## Overview

A Subnet policy group enables automatic policy selection based on the current network environment using subnet expressions as conditions.

## Basic Syntax

```
Subnet Group = subnet, default = ProxyHTTP, TYPE:WIFI = ProxyHTTP, SSID:MyHome = ProxySOCKS5
```

## Key Information

**Naming Convention:** Starting with Surge iOS 4.12.0 and Surge Mac 4.5.0, the SSID group was renamed to Subnet Group. Legacy SSID Group syntax remains supported for backwards compatibility. Both `subnet` and `ssid` keywords work.

## Parameters

### `default` (Required)
Specifies the policy applied when no subnet expression matches the current network.

### `cellular` (Optional, Deprecated)
Previously used to designate policy for cellular networks. Use `TYPE:CELLULAR` instead for current implementations. If omitted, the default policy applies.

## Related Concepts

This feature integrates with subnet expressions to create conditional routing rules based on network characteristics like connection type and SSID names.


## Url test

# Automatic Testing Group

## Overview

The Automatic Testing Group dynamically selects a proxy policy based on latency benchmarking to a specified testing URL. This selection can be overridden temporarily or adjusted through general settings.

**Basic Syntax:**
```
AutoTestGroup = url-test, ProxySOCKS5, ProxySOCKS5TLS
```

## Temporary Override

Manual policy selection can temporarily override automatic testing results:

- **Surge Mac:** Access the override option via the main menu within the corresponding group
- **Surge iOS:** Long-press on the policy's menu in the policy group view

## Configuration Parameters

**interval** (Optional, seconds | Default: 600)
Benchmark results expire after this duration. Retesting occurs if the policy group is subsequently accessed.

**tolerance** (Optional, milliseconds | Default: 100)
The policy will be changed only when the new winner has a higher score than the old winner's score plus the tolerance. This prevents frequent switching between similarly-performing policies.

**timeout** (Optional, seconds | Default: 5)
Policies that fail to complete within this timeframe are abandoned.

**evaluate-before-use** (Optional, Boolean | Default: false)
By default, the first policy is used initially while testing runs in the background. When enabled, testing completes before the first request is made.