Profile

The profile is the source of truth for Surge behavior. Most profile content can be adjusted in the user interface, but advanced or experimental features may still require manual editing.

Profile Format

Surge profiles use an INI-like format. Content is divided into sections such as [General], [Proxy], [Proxy Group], and [Rule].

Each section has its own syntax. For example, [General] and [MITM] use key = value lines:

[General]
key = value

In sections such as [General], line order usually does not matter. In ordered sections such as [Rule], line order is part of the behavior.

Profile Types

Profiles are divided into three categories:

  1. Normal profile: created manually or used by default.
  2. Managed profile: usually provided by the enterprise administrator or service provider. The managed profile cannot be modified locally because it can be updated remotely. If you want to make changes, you should first create a copy to transfer it to a normal configuration.
  3. Enterprise profile: Enterprise version only, cannot be modified or viewed, and cannot be copied.

Detached Profile Section

To support complex setups, Surge can split one or more sections into another file.

Example:

Main.conf

[Proxy]
#!include Proxy.dconf

The referenced file must contain the corresponding section declaration. The file can contain one section, multiple sections, or a complete profile.

Proxy.dconf

[Proxy]
ProxyA = http, 1.2.3.4, 80

This is useful when you want to:

  1. Reference the [Proxy], [Proxy Group], and [Rule] sections of a managed profile while writing other sections yourself. This keeps proxy-related content updated without affecting local UI-managed settings.
  2. Share sections across multiple profiles. For example, when using Surge on both iOS and macOS, [Proxy], [Proxy Group], and [Rule] are often the same, while [General] may be different. You can create iOS.conf and macOS.conf, then place the shared sections in another file.
[Proxy]
#!include Forwarding.dconf

[Proxy Group]
#!include Forwarding.dconf

[Rule]
#!include Forwarding.dconf

This way, adjusting [General] on iOS does not affect macOS, and you do not need to maintain two copies of the same routing configuration.

Additional notes:

  • After modifying the profile in the UI, Surge writes the section back to the corresponding detached profile according to the include statement. If the included file contains other unused sections, only the used section is modified.
  • If a managed profile is referenced, the referenced section cannot be edited locally, but other sections remain editable.
  • A filename suffix is not required. If the file is a complete profile, you can continue using .conf. If it is not a complete profile, use another suffix to avoid showing it in the profile list.

  • Starting from Surge iOS 4.12.0 and Surge Mac 4.5.0, one section can include multiple detached profiles. That section is marked read-only and cannot be edited in the UI.

      [Proxy]
  #!include A.dconf, B.dconf

Linked Profiles Mac 6.0.0+

#!include can also reference a remote managed profile (a URL) directly. This lets you build a local “overlay” profile that keeps following updates from the upstream config.

[Rule]
#!include https://example.com/managed.conf

When the referenced content is read-only, Surge will prompt to create a linked layer if you try to edit those sections. The local layer stores only your overrides, while the remote managed profile keeps receiving updates automatically.

Modules

Detached profile sections split one profile into multiple files. Modules are different: they patch selected parts of a profile to enable a specific behavior.

Modules can:

  • Be turned on and off independently.
  • Tune multiple sections from one module file.
  • Be installed and kept up to date by URL.

However:

  • Modules cannot adjust the content of [Proxy], [Proxy Group], or [Rule] sections.
  • The module cannot adjust the CA certificate of MITM.
  • The settings of the module override the main profile, so they cannot be adjusted via the UI.

The module description is available at: https://manual.nssurge.com/others/module.html

Comments

Surge profiles support comment lines that start with #, ;, or //. Inline comments are also supported.

# This is a comment line.
; This is a comment line.
// This is a comment line.

dns-server = 8.8.8.8 // This is an inline comment.
dns-server = 8.8.8.8 # This is an inline comment.
dns-server = 8.8.8.8 ; This is an inline comment.

When using inline comments, there must be at least one space before the delimiter.

Line Requirement iOS 5.11.0+ Mac 5.7.0+

You can set constraints to make a certain line configuration effective only when specific conditions are met.

Group = url, policyA, policyB #!REQUIREMENT CORE_VERSION<22

For items that support an enabled/disabled state, lines that do not meet the conditions are treated as disabled. Other unmatched lines are treated as comments.

#!REQUIREMENT expressions can also be used at the beginning of a line. Since previous versions did not support this expression, both end-of-line and start-of-line formats are provided. This mechanism can be flexibly utilized to support older versions. For example, if you want clients that support Smart groups to use Smart groups, you can write it as

#!REQUIREMENT CORE_VERSION>=22 Group = smart, policyA, policyB
Group = url, policyA, policyB //!REQUIREMENT CORE_VERSION<22

In older versions, the first line is treated as a normal comment and has no effect. The end-of-line requirement on the second line is also treated as a regular comment.

REQUIREMENT Expression

Variables available for judgment include CORE_VERSION, SYSTEM, SYSTEM_VERSION, DEVICE_MODEL, LANGUAGE.

Operators that can be used are =,==,>=,=>,<=,=<,>,<,!=,<>,AND,&&,OR,||,NOT,!,BEGINSWITH,CONTAINS,ENDSWITH,LIKE,MATCHES.

A typical example of variable values:

CORE_VERSION: 22
SYSTEM: iOS
SYSTEM_VERSION: System Version 17.4.1 (Build 21E236)
DEVICE_MODEL: iPhone16,1
LANGUAGE: en-US

Strings in expressions should be enclosed in '', such as #!REQUIREMENT SYSTEM=='macOS'

Simplified Notation iOS 5.14.3+ Mac 5.10.0+

Provides three simplified notations #!IOS-ONLY, #!MACOS-ONLY, #!TVOS-ONLY for convenience.

For example,

DOMAIN,reject.com,REJECT #!MACOS-ONLY

results matching ""

    No results matching ""