# Overview

> Components and configuration basics

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

---

## Components

# Components

Surge includes several components.

## Surge Proxy Server

The core component of Surge is a full-function HTTP/SOCKS5 proxy server. Built using Objective-C and optimized for macOS and iOS, it delivers high performance and stability.

## Surge Virtual Network Interface (Surge VIF)

Certain applications bypass system proxy settings because they require raw TCP socket access (Mail.app serves as an example). The Surge VIF handles this type of traffic.

For Surge iOS, this component is enabled by default. On Surge Mac, you can activate it by enabling Enhanced Mode.

## Surge Dashboard (Mac Version Only)

Available exclusively on Mac, Surge Dashboard provides a graphical interface for monitoring and inspecting requests and reviewing DNS cache information. It can connect to either a local Surge instance or a remote instance when external-controller-access is configured.


## Configuration

# Profile

The core functionality of Surge is controlled by the profile. While most settings can be adjusted through the user interface, certain experimental features may require manual editing to access.

## Profile Content

Profiles follow INI file format with `[Section]` segments organizing different settings. Most sections use `key = value` syntax:

```
[General]
key = value
```

In sections like `[General]` and `[MITM]`, configuration line order doesn't matter. However, in sections such as `[Rule]`, order is critically important.

## Profile Classifications

Profiles fall into three categories:

1. **Normal profile** — manually created or default
2. **Managed profile** — typically supplied by administrators; cannot be locally modified but can be updated remotely. Create a copy to make changes.
3. **Enterprise profile** — enterprise version only; cannot be modified, viewed, or copied

## Detached Profile Sections

Surge supports separating profile sections into separate files for managing complex configurations.

**Main.conf example:**
```
[Proxy]
#!include Proxy.dconf
```

**Proxy.dconf must contain:**
```
[Proxy]
ProxyA = http, 1.2.3.4, 80
```

This enables:
- Referencing managed configuration sections while customizing others locally
- Sharing sections across multiple profiles
- Maintaining consistency between iOS and macOS configurations

**Multiple includes (Surge iOS 4.12.0+, Mac 4.5.0+):**
```
[Proxy]
#!include A.dconf, B.dconf
```

When multiple files are included, the section becomes read-only via UI.

### Linked Profiles (Mac 6.0.0+)

Include remote managed profiles directly:
```
[Rule]
#!include https://example.com/managed.conf
```

This creates a local "overlay" receiving automatic upstream updates.

## Modules

Modules are patches applied to profiles for specific tasks. They differ from detached sections by offering:

- **Flexible toggling** on and off
- **Multi-section tuning** within one file
- **URL-based installation and updates**

**Limitations:**
- Cannot adjust `[Proxy]`, `[Proxy Group]`, or `[Rule]` sections
- Cannot modify MITM CA certificates
- Settings override main profile configuration (not adjustable via UI)

## Comments

Three comment formats are supported:
```
# Comment
; Comment
// Comment
```

Inline comments require at least one space before the delimiter:
```
dns-server = 8.8.8.8 // inline comment
```

## Line Requirements (iOS 5.11.0+, Mac 5.7.0+)

Conditionally activate configuration lines using `#!REQUIREMENT`:
```
Group = url, policyA, policyB #!REQUIREMENT CORE_VERSION<22
```

**Available variables:** `CORE_VERSION`, `SYSTEM`, `SYSTEM_VERSION`, `DEVICE_MODEL`, `LANGUAGE`

**Supported operators:** `=, ==, >=, <=, >, <, !=, AND, OR, NOT, BEGINSWITH, CONTAINS, ENDSWITH, LIKE, MATCHES`

**Simplified notation (iOS 5.14.3+, Mac 5.10.0+):**
```
DOMAIN,reject.com,REJECT #!MACOS-ONLY
```