### Configuration Examples

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/experimental/clash-api.zh.md

Examples of sing-box configuration, demonstrating different use cases.

```APIDOC
### Example (Online)

!!! question "Since sing-box 1.10.0"

```json
{
  "external_controller": "127.0.0.1:9090",
  "access_control_allow_origin": [
    "http://127.0.0.1",
    "http://yacd.haishan.me"
  ],
  "access_control_allow_private_network": true
}
```

### Example (Download)

!!! question "Since sing-box 1.10.0"

```json
{
  "external_controller": "0.0.0.0:9090",
  "external_ui": "dashboard"
  // "external_ui_download_detour": "direct"
}
```

!!! note ""

When there is only one item in the content, the JSON array [] tag can be omitted.
```

--------------------------------

### Install sing-box binary

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.zh.md

Builds the binary and installs it to your Go binary directory ($GOBIN).

```bash
make install
```

--------------------------------

### Build and Install sing-box

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.md

Builds sing-box and installs the binary to your Go binary directory. Requires a Go environment.

```bash
make install
```

--------------------------------

### TUN Inbound Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/inbound/tun.md

This is a comprehensive example of a TUN inbound configuration, showcasing various fields for network interface setup, DNS hijacking, routing, and platform-specific settings. Ensure correct permissions if running in non-privileged mode.

```json
{
  "type": "tun",
  "tag": "tun-in",
  "interface_name": "tun0",
  "address": [
    "172.18.0.1/30",
    "fdfe:dcba:9876::1/126"
  ],
  "mtu": 9000,
  "dns_mode": "hijack",
  "dns_address": [
    "172.18.0.2",
    "fdfe:dcba:9876::2"
  ],
  "auto_route": true,
  "iproute2_table_index": 2022,
  "iproute2_rule_index": 9000,
  "auto_redirect": true,
  "auto_redirect_input_mark": "0x2023",
  "auto_redirect_output_mark": "0x2024",
  "auto_redirect_reset_mark": "0x2025",
  "auto_redirect_nfqueue": 100,
  "auto_redirect_iproute2_fallback_rule_index": 32768,
  "exclude_mptcp": false,
  "loopback_address": [
    "10.7.0.1"
  ],
  "strict_route": true,
  "route_address": [
    "0.0.0.0/1",
    "128.0.0.0/1",
    "::/1",
    "8000::/1"
  ],
  "route_exclude_address": [
    "192.168.0.0/16",
    "fc00::/7"
  ],
  "route_address_set": [
    "geoip-cloudflare"
  ],
  "route_exclude_address_set": [
    "geoip-cn"
  ],
  "endpoint_independent_nat": false,
  "udp_timeout": "5m",
  "stack": "system",
  "include_interface": [
    "lan0"
  ],
  "exclude_interface": [
    "lan1"
  ],
  "include_uid": [
    0
  ],
  "include_uid_range": [
    "1000:99999"
  ],
  "exclude_uid": [
    1000
  ],
  "exclude_uid_range": [
    "1000:99999"
  ],
  "include_android_user": [
    0,
    10
  ],
  "include_package": [
    "com.android.chrome"
  ],
  "exclude_package": [
    "com.android.captiveportallogin"
  ],
  "include_mac_address": [
    "00:11:22:33:44:55"
  ],
  "exclude_mac_address": [
    "66:77:88:99:aa:bb"
  ],
  "platform": {
    "http_proxy": {
      "enabled": false,
      "server": "127.0.0.1",
      "server_port": 8080,
      "bypass_domain": [],
      "match_domain": []
    }
  },
  "gso": false,
  "inet4_address": [
    "172.19.0.1/30"
  ],
  "inet6_address": [
    "fdfe:dcba:9876::1/126"
  ],
  "inet4_route_address": [
    "0.0.0.0/1",
    "128.0.0.0/1"
  ],
  "inet6_route_address": [
    "::/1",
    "8000::/1"
  ],
  "inet4_route_exclude_address": [
    "192.168.0.0/16"
  ],
  "inet6_route_exclude_address": [
    "fc00::/7"
  ]
}
```

--------------------------------

### Sing-box Example Configuration (Download)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/experimental/clash-api.md

An example sing-box configuration for downloading external UI resources. It specifies the external controller address and the UI to be used. This configuration is effective from sing-box version 1.10.0.

```json
{
  "external_controller": "0.0.0.0:9090",
  "external_ui": "dashboard"
  // "external_ui_download_detour": "direct"
}
```

--------------------------------

### Sing-box Example Configuration (Online)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/experimental/clash-api.md

An example of a sing-box configuration for online use, demonstrating settings for external controller, CORS allowed origins, and private network access. This configuration is effective from sing-box version 1.10.0.

```json
{
  "external_controller": "127.0.0.1:9090",
  "access_control_allow_origin": [
    "http://127.0.0.1",
    "http://yacd.haishan.me"
  ],
  "access_control_allow_private_network": true
}
```

--------------------------------

### Simple Build sing-box

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.md

Use this command for a basic build of sing-box. Ensure you have the required Go version installed.

```bash
make
```

--------------------------------

### Clash API Dashboard Download Configuration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/experimental/clash-api.zh.md

Example configuration for setting up a dashboard UI via download.

```json
{
  "external_controller": "0.0.0.0:9090",
  "external_ui": "dashboard"
  // "external_ui_download_detour": "direct"
}
```

--------------------------------

### Sing-box Inbound TLS Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/shared/tls.md

Example JSON structure for configuring TLS settings on inbound connections. This includes fields for server name, ALPN, certificate management, and client authentication.

```json
{
  "enabled": true,
  "server_name": "",
  "alpn": [],
  "min_version": "",
  "max_version": "",
  "cipher_suites": [],
  "curve_preferences": [],
  "certificate": [],
  "certificate_path": "",
  "client_authentication": "",
  "client_certificate": [],
  "client_certificate_path": [],
  "client_certificate_public_key_sha256": [],
  "key": [],
  "key_path": "",
  "kernel_tx": false,
  "kernel_rx": false,
  "handshake_timeout": "",
  "certificate_provider": "",

  "acme": {
    "domain": [],
    "data_directory": "",
    "default_server_name": "",
    "email": "",
    "provider": "",
    "disable_http_challenge": false,
    "disable_tls_alpn_challenge": false,
    "alternative_http_port": 0,
    "alternative_tls_port": 0,
    "external_account": {
      "key_id": "",
      "mac_key": ""
    },
    "dns01_challenge": {}
  },
  "ech": {
    "enabled": false,
    "key": [],
    "key_path": "",

    "pq_signature_schemes_enabled": false,
    "dynamic_record_sizing_disabled": false
  },
  "reality": {
    "enabled": false,
    "handshake": {
      "server": "google.com",
      "server_port": 443,

      ... // Dial Fields
    },
    "private_key": "UuMBgl7MXTPx9inmQp2UC7Jcnwc6XYbwDNebonM-FCc",
    "short_id": [
      "0123456789abcdef"
    ],
    "max_time_difference": "1m"
  }
}
```

--------------------------------

### Neighbor Domain Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/server/local.md

Illustrates how to configure neighbor domains for the local DNS server. Queries for these domains will be resolved using the neighbor resolver.

```json
".", ".lan"
```

--------------------------------

### Sing-box Outbound TLS Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/shared/tls.md

Example JSON structure for configuring TLS settings on outbound connections. This includes fields for engine, server name, SNI disabling, and advanced features like UTLS and REALITY.

```json
{
  "enabled": true,
  "engine": "",
  "disable_sni": false,
  "server_name": "",
  "insecure": false,
  "alpn": [],
  "min_version": "",
  "max_version": "",
  "cipher_suites": [],
  "curve_preferences": [],
  "certificate": "",
  "certificate_path": "",
  "certificate_public_key_sha256": [],
  "client_certificate": [],
  "client_certificate_path": "",
  "client_key": [],
  "client_key_path": "",
  "fragment": false,
  "fragment_fallback_delay": "",
  "record_fragment": false,
  "spoof": "",
  "spoof_method": "",
  "kernel_tx": false,
  "kernel_rx": false,
  "handshake_timeout": "",
  "ech": {
    "enabled": false,
    "config": [],
    "config_path": "",
    "query_server_name": "",

    "pq_signature_schemes_enabled": false,
    "dynamic_record_sizing_disabled": false
  },
  "utls": {
    "enabled": false,
    "fingerprint": ""
  },
  "reality": {
    "enabled": false,
    "public_key": "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0",
    "short_id": "0123456789abcdef"
  }
}
```

--------------------------------

### Service Structure Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/service/index.md

Defines the basic JSON structure for the 'services' array in the sing-box configuration. Each service object requires a 'type' and a 'tag'.

```json
{
  "services": [
    {
      "type": "",
      "tag": ""
    }
  ]
}
```

--------------------------------

### Define sing-box routing rules

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/rule-set/headless-rule.md

Example configuration showing the structure of rule objects, including standard matchers and logical rule types.

```json
{
  "rules": [
    {
      "query_type": [
        "A",
        "HTTPS",
        32768
      ],
      "network": [
        "tcp"
      ],
      "domain": [
        "test.com"
      ],
      "domain_suffix": [
        ".cn"
      ],
      "domain_keyword": [
        "test"
      ],
      "domain_regex": [
        "^stun\\..+"
      ],
      "source_ip_cidr": [
        "10.0.0.0/24",
        "192.168.0.1"
      ],
      "ip_cidr": [
        "10.0.0.0/24",
        "192.168.0.1"
      ],
      "source_port": [
        12345
      ],
      "source_port_range": [
        "1000:2000",
        ":3000",
        "4000:"
      ],
      "port": [
        80,
        443
      ],
      "port_range": [
        "1000:2000",
        ":3000",
        "4000:"
      ],
      "process_name": [
        "curl"
      ],
      "process_path": [
        "/usr/bin/curl"
      ],
      "process_path_regex": [
        "^/usr/bin/.+"
      ],
      "package_name": [
        "com.termux"
      ],
      "package_name_regex": [
        "^com\\.termux.*"
      ],
      "network_type": [
        "wifi"
      ],
      "network_is_expensive": false,
      "network_is_constrained": false,
      "network_interface_address": {
        "wifi": [
          "2000::/3"
        ]
      },
      "default_interface_address": [
        "2000::/3"
      ],
      "wifi_ssid": [
        "My WIFI"
      ],
      "wifi_bssid": [
        "00:00:00:00:00:00"
      ],
      "invert": false
    },
    {
      "type": "logical",
      "mode": "and",
      "rules": [],
      "invert": false
    }
  ]
}
```

--------------------------------

### Split DNS Configuration with Resolved (sing-box < 1.14.0)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/server/resolved.md

This configuration sets up split DNS using both a local DNS server and the Resolved DNS server. It uses 'ip_accept_any' for routing. This example is for sing-box versions prior to 1.14.0.

```json
{
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      },
      {
        "type": "resolved",
        "tag": "resolved",
        "service": "resolved"
      }
    ],
    "rules": [
      {
        "ip_accept_any": true,
        "server": "resolved"
      }
    ]
  }
}
```

--------------------------------

### Trojan Inbound Configuration Example (JSON)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/inbound/trojan.md

An example JSON structure for configuring the Trojan inbound protocol in Sing-box. This includes essential fields like type, tag, user credentials, TLS settings, and fallback options.

```json
{
  "type": "trojan",
  "tag": "trojan-in",
  "users": [
    {
      "name": "sekai",
      "password": "8JCsPssfgS8tiRwiMlhARg=="
    }
  ],
  "tls": {},
  "fallback": {
    "server": "127.0.0.1",
    "server_port": 8080
  },
  "fallback_for_alpn": {
    "http/1.1": {
      "server": "127.0.0.1",
      "server_port": 8081
    }
  },
  "multiplex": {},
  "transport": {}
}
```

--------------------------------

### Enable Tailscale SSH Server

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/endpoint/tailscale.md

Enables the Tailscale SSH server. This is the basic configuration to start the server.

```json
{
  "enabled": true,
  "disable_pty": false,
  "disable_sftp": false,
  "disable_forwarding": false
}
```

--------------------------------

### Selector Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/outbound/selector.md

This JSON snippet demonstrates the structure of a selector configuration in Sing-box. It defines the type as 'selector', assigns a tag, lists available outbounds, specifies a default outbound, and configures whether to interrupt existing connections.

```json
{
  "type": "selector",
  "tag": "select",
  
  "outbounds": [
    "proxy-a",
    "proxy-b",
    "proxy-c"
  ],
  "default": "proxy-c",
  "interrupt_exist_connections": false
}
```

--------------------------------

### Custom Build sing-box with Tags

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.md

Build sing-box with specific build tags enabled. This allows for conditional compilation of features. Ensure Go and make are installed.

```bash
TAGS="tag_a tag_b" make
```

--------------------------------

### Sing-Box Route Rules: Basic Setup (JSON)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/manual/proxy/client.md

This JSON snippet defines basic routing rules for Sing-Box, including outbound configurations and DNS hijacking. It sets up a 'direct' outbound and hijacks DNS traffic on port 53 or for DNS protocol.

```json
{
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "action": "sniff"
      },
      {
        "type": "logical",
        "mode": "or",
        "rules": [
          {
            "protocol": "dns"
          },
          {
            "port": 53
          }
        ],
        "action": "hijack-dns"
      },
      {

```

--------------------------------

### Configure Shadowsocks client in sing-box

Source: https://github.com/sagernet/sing-box/blob/testing/docs/manual/proxy-protocol/shadowsocks.md

JSON configuration examples for setting up a Shadowsocks outbound client. Demonstrates how to connect to single-user and multi-user servers.

```json
{
  "outbounds": [
    {
      "type": "shadowsocks",
      "server": "127.0.0.1",
      "server_port": 8080,
      "method": "2022-blake3-aes-128-gcm",
      "password": "<pasword>",
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

```json
{
  "outbounds": [
    {
      "type": "shadowsocks",
      "server": "127.0.0.1",
      "server_port": 8080,
      "method": "2022-blake3-aes-128-gcm",
      "password": "<server_pasword>:<user_password>",
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

--------------------------------

### Split DNS Configuration with Resolved (sing-box 1.14.0+)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/server/resolved.md

This configuration sets up split DNS using both a local DNS server and the Resolved DNS server. It routes preferred queries to the Resolved server. This example is for sing-box version 1.14.0 and later.

```json
{
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      },
      {
        "type": "resolved",
        "tag": "resolved",
        "service": "resolved"
      }
    ],
    "rules": [
      {
        "preferred_by": "resolved",
        "action": "route",
        "server": "resolved"
      }
    ]
  }
}
```

--------------------------------

### Configure TCP Brutal

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/shared/tcp-brutal.md

Enable TCP Brutal and set upload/download bandwidth limits in Mbps. Ensure the 'brutal' congestion control algorithm is installed on your Linux system.

```json
{
  "enabled": true,
  "up_mbps": 100,
  "down_mbps": 100
}
```

--------------------------------

### ShadowTLS Outbound Configuration Example (JSON)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/outbound/shadowtls.md

This JSON snippet demonstrates the structure for configuring a ShadowTLS outbound connection in sing-box. It includes essential fields such as the server address, port, ShadowTLS version, and password. The 'tls' field requires a separate TLS configuration.

```json
{
  "type": "shadowtls",
  "tag": "st-out",
  "server": "127.0.0.1",
  "server_port": 1080,
  "version": 3,
  "password": "fuck me till the daylight",
  "tls": {}
}
```

--------------------------------

### DNS Rule Structure Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/rule.md

This JSON object demonstrates the comprehensive structure of a single DNS rule, showcasing various matching conditions and actions. It includes fields for inbound connections, IP versions, query types, network protocols, domain matching, source IP and port filtering, process information, user identification, network interfaces, and rule sets. The 'action' field specifies 'route' and the 'server' field indicates 'local' for this rule.

```json
{
  "dns": {
    "rules": [
      {
        "inbound": [
          "mixed-in"
        ],
        "ip_version": 6,
        "query_type": [
          "A",
          "HTTPS",
          32768
        ],
        "network": "tcp",
        "auth_user": [
          "usera",
          "userb"
        ],
        "protocol": [
          "tls",
          "http",
          "quic"
        ],
        "domain": [
          "test.com"
        ],
        "domain_suffix": [
          ".cn"
        ],
        "domain_keyword": [
          "test"
        ],
        "domain_regex": [
          "^stun\\..+"
        ],
        "source_ip_cidr": [
          "10.0.0.0/24",
          "192.168.0.1"
        ],
        "source_ip_is_private": false,
        "source_port": [
          12345
        ],
        "source_port_range": [
          "1000:2000",
          ":3000",
          "4000:"
        ],
        "port": [
          80,
          443
        ],
        "port_range": [
          "1000:2000",
          ":3000",
          "4000:"
        ],
        "process_name": [
          "curl"
        ],
        "process_path": [
          "/usr/bin/curl"
        ],
        "process_path_regex": [
          "^/usr/bin/.+"
        ],
        "package_name": [
          "com.termux"
        ],
        "package_name_regex": [
          "^com\\.termux.*"
        ],
        "user": [
          "sekai"
        ],
        "user_id": [
          1000
        ],
        "clash_mode": "direct",
        "network_type": [
          "wifi"
        ],
        "network_is_expensive": false,
        "network_is_constrained": false,
        "interface_address": {
          "en0": [
            "2000::/3"
          ]
        },
        "network_interface_address": {
          "wifi": [
            "2000::/3"
          ]
        },
        "default_interface_address": [
          "2000::/3"
        ],
        "source_mac_address": [
          "00:11:22:33:44:55"
        ],
        "source_hostname": [
          "my-device"
        ],
        "preferred_by": [
          "local",
          "ts-dns"
        ],
        "wifi_ssid": [
          "My WIFI"
        ],
        "wifi_bssid": [
          "00:00:00:00:00:00"
        ],
        "rule_set": [
          "geoip-cn",
          "geosite-cn"
        ],
        "rule_set_ip_cidr_match_source": false,
        "match_response": false,
        "ip_cidr": [
          "10.0.0.0/24",
          "192.168.0.1"
        ],
        "ip_is_private": false,
        "ip_accept_any": false,
        "response_rcode": "",
        "response_answer": [],
        "response_ns": [],
        "response_extra": [],
        "invert": false,
        "outbound": [
          "direct"
        ],
        "action": "route",
        "server": "local",
        "rule_set_ip_cidr_accept_empty": false,
        "rule_set_ipcidr_match_source": false,
        "geosite": [
          "cn"
        ],
        "source_geoip": [
          "private"
        ],
        "geoip": [
          "cn"
        ]
      },
      {
        "type": "logical",
        "mode": "and",
        "rules": [],
        "action": "route",
        "server": "local"
      }
    ]
  }
}
```

--------------------------------

### Manually Install Sing-Box using Install Script

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/package-manager.md

Installs the latest Sing-Box package from GitHub releases using a shell script. This method is suitable for various Linux distributions, including Debian/RPM-based systems, ArchLinux, and OpenWrt. It supports installing the latest stable, beta, or a specific version of Sing-Box.

```shell
curl -fsSL https://sing-box.app/install.sh | sh
```

```shell
curl -fsSL https://sing-box.app/install.sh | sh -s -- --beta
```

```shell
curl -fsSL https://sing-box.app/install.sh | sh -s -- --version <version>
```

--------------------------------

### Build sing-box

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.zh.md

Run this command in the project root to build sing-box with default settings.

```bash
make
```

--------------------------------

### Install Sing-Box on Debian/Ubuntu using APT

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/package-manager.md

Installs the Sing-Box package on Debian-based systems using the APT package manager. This involves adding the official Sing-Box repository and GPG key before updating the package list and installing the package. It supports both stable and beta versions.

```bash
sudo mkdir -p /etc/apt/keyrings &&
   sudo curl -fsSL https://sing-box.app/gpg.key -o /etc/apt/keyrings/sagernet.asc &&
   sudo chmod a+r /etc/apt/keyrings/sagernet.asc &&
   echo '
Types: deb
URIs: https://deb.sagernet.org/
Suites: *
Components: *
Enabled: yes
Signed-By: /etc/apt/keyrings/sagernet.asc
' | sudo tee /etc/apt/sources.list.d/sagernet.sources &&
   sudo apt-get update &&
   sudo apt-get install sing-box # or sing-box-beta
```

--------------------------------

### Install Sing-Box on Red Hat/Fedora using DNF

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/package-manager.md

Installs the Sing-Box package on Red Hat-based systems using the DNF package manager. This method adds the Sing-Box repository configuration and then installs the package. It supports DNF versions 4 and 5, with version 4 requiring the `dnf-plugins-core` package.

```bash
sudo dnf config-manager addrepo --from-repofile=https://sing-box.app/sing-box.repo &&
sudo dnf install sing-box # or sing-box-beta
```

```bash
sudo dnf config-manager --add-repo https://sing-box.app/sing-box.repo &&
sudo dnf -y install dnf-plugins-core &&
sudo dnf install sing-box # or sing-box-beta
```

--------------------------------

### Sing-box Inbound Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/shared/multiplex.md

An example of an inbound configuration block for sing-box. It enables multiplexing support and specifies padding behavior.

```json
{
  "enabled": true,
  "padding": false,
  "brutal": {}
}
```

--------------------------------

### Sing-box Outbound Configuration Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/shared/multiplex.md

An example of an outbound configuration block for sing-box. It enables multiplexing, specifies the protocol (smux), and sets connection limits.

```json
{
  "enabled": true,
  "protocol": "smux",
  "max_connections": 4,
  "min_streams": 4,
  "max_streams": 0,
  "padding": false,
  "brutal": {}
}
```

--------------------------------

### Custom build with tags using make

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.zh.md

Build sing-box with specific build tags enabled using the make command. Replace tag_a and tag_b with desired tags.

```bash
TAGS="tag_a tag_b" make
```

--------------------------------

### Custom build with tags using go build

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.zh.md

Build sing-box with specific build tags enabled using the go build command. Replace tag_a and tag_b with desired tags.

```bash
go build -tags "tag_a tag_b" ./cmd/sing-box
```

--------------------------------

### SSM API Server Mapping Example

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/service/ssm-api.md

An example of the required 'servers' field, which maps HTTP endpoints to specific Shadowsocks inbound tags. These inbounds must have the 'managed' property enabled.

```json
{
  "servers": {
    "/": "ss-in"
  }
}
```

--------------------------------

### GET /config/endpoints

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/endpoint/index.md

Defines the structure for configuring endpoints within the sing-box configuration file.

```APIDOC
## Endpoint Configuration Structure

### Description
Defines the protocol-specific behavior for inbound and outbound traffic within the sing-box configuration.

### Method
N/A (Configuration Object)

### Endpoint
endpoints[]

### Parameters
#### Request Body
- **type** (string) - Required - The protocol type of the endpoint (e.g., "wireguard", "tailscale").
- **tag** (string) - Required - A unique identifier for the endpoint.

### Request Example
{
  "endpoints": [
    {
      "type": "wireguard",
      "tag": "wg-inbound"
    }
  ]
}

### Response
#### Success Response (200)
- **endpoints** (array) - List of configured endpoints.
```

--------------------------------

### Custom Build sing-box with go build and Tags

Source: https://github.com/sagernet/sing-box/blob/testing/docs/installation/build-from-source.md

Alternatively, use the go build command directly with build tags to compile sing-box. This method is useful for more granular control over the build process.

```bash
go build -tags "tag_a tag_b" ./cmd/sing-box
```

--------------------------------

### Enable Tailscale SSH Server (Shorthand)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/endpoint/tailscale.md

A shorthand for enabling the SSH server with default settings.

```json
true
```

--------------------------------

### Hysteria2 Inbound Configuration Structure

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/inbound/hysteria2.md

A comprehensive example of the Hysteria2 inbound configuration object, showcasing various fields and their nested structures.

```json
{
  "type": "hysteria2",
  "tag": "hy2-in",
  
  ... // Listen Fields

  "up_mbps": 100,
  "down_mbps": 100,
  "obfs": {
    "type": "salamander",
    "password": "cry_me_a_r1ver"
  },
  "users": [
    {
      "name": "tobyxdd",
      "password": "goofy_ahh_password"
    }
  ],
  "ignore_client_bandwidth": false,
  "tls": {},

  ... // QUIC Fields

  "masquerade": "", // or {}
  "bbr_profile": "",
  "brutal_debug": false,
  "realm": {
    "server_url": "https://realm.example.com",
    "token": "",
    "realm_id": "",
    "stun_servers": [],
    "stun_domain_resolver": "", // or {}
    "http_client": {}
  }
}
```

--------------------------------

### STUN Server Configuration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/service/derp.md

Options for enabling and configuring the STUN server.

```json
{
  "enabled": true,
  
  ... // Listen Fields
}
```

```json
{ "enabled": true, "listen_port": __PORT__ }
```

--------------------------------

### Clash API Online Access Configuration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/experimental/clash-api.zh.md

Example configuration for enabling online access to the Clash API using CORS settings.

```json
{
  "external_controller": "127.0.0.1:9090",
  "access_control_allow_origin": [
    "http://127.0.0.1",
    "http://yacd.haishan.me"
  ],
  "access_control_allow_private_network": true
}
```

--------------------------------

### Configure Hosts File Path

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/server/hosts.md

Specify a list of paths to custom hosts files. Defaults to system hosts files if not provided.

```json
{
  // "path": "/etc/hosts"
  
  "path": [
    "/etc/hosts",
    "$HOME/.hosts"
  ]
}
```

--------------------------------

### Format Sing-box Configuration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/index.md

The 'format' command helps in pretty-printing and standardizing the JSON configuration file. The '-w' flag writes the changes back to the file.

```bash
sing-box format -w -c config.json -D config_directory
```

--------------------------------

### Use Hosts DNS Server (sing-box >= 1.14.0)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/server/hosts.md

Integrates the 'hosts' DNS server and routes traffic to it using a rule. Requires sing-box version 1.14.0 or later.

```json
{
  "dns": {
    "servers": [
      {
        ... 
      },
      {
        "type": "hosts",
        "tag": "hosts"
      }
    ],
    "rules": [
      {
        "preferred_by": "hosts",
        "action": "route",
        "server": "hosts"
      }
    ]
  }
}
```

--------------------------------

### OCM Server Example (JSON)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/service/ocm.md

A basic JSON configuration for running the OCM service on a server, specifying the listen address and port.

```json
{
  "services": [
    {
      "type": "ocm",
      "listen": "127.0.0.1",
      "listen_port": 8080
    }
  ]
}
```

--------------------------------

### Migrate QUIC DNS Server Configuration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/migration.md

Illustrates the format change for QUIC DNS servers, from deprecated to new.

```json
{
  "dns": {
    "servers": [
      {
        "address": "quic://1.1.1.1"
      }
    ]
  }
}
```

```json
{
  "dns": {
    "servers": [
      {
        "type": "quic",
        "server": "1.1.1.1"
      }
    ]
  }
}
```

--------------------------------

### Trojan Server Configuration JSON

Source: https://github.com/sagernet/sing-box/blob/testing/docs/manual/proxy-protocol/trojan.md

Provides examples of Trojan server configurations in JSON format. These configurations demonstrate different methods for TLS certificate management, including local files and ACME.

```json
{
  "inbounds": [
    {
      "type": "trojan",
      "listen": "::",
      "listen_port": 8080,
      "users": [
        {
          "name": "example",
          "password": "password"
        }
      ],
      "tls": {
        "enabled": true,
        "server_name": "example.org",
        "key_path": "/path/to/key.pem",
        "certificate_path": "/path/to/certificate.pem"
      },
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

```json
{
  "inbounds": [
    {
      "type": "trojan",
      "listen": "::",
      "listen_port": 8080,
      "users": [
        {
          "name": "example",
          "password": "password"
        }
      ],
      "tls": {
        "enabled": true,
        "server_name": "example.org",
        "acme": {
          "domain": "example.org",
          "email": "admin@example.org"
        }
      },
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

```json
{
  "inbounds": [
    {
      "type": "trojan",
      "listen": "::",
      "listen_port": 8080,
      "users": [
        {
          "name": "example",
          "password": "password"
        }
      ],
      "tls": {
        "enabled": true,
        "server_name": "example.org",
        "acme": {
          "domain": "example.org",
          "email": "admin@example.org",
          "dns01_challenge": {
            "provider": "cloudflare",
            "api_token": "my_token"
          }
        }
      },
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

--------------------------------

### Migrate TLS DNS Server Configuration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/migration.md

Demonstrates the change in format for TLS DNS server configurations.

```json
{
  "dns": {
    "servers": [
      {
        "address": "tls://1.1.1.1"
      }
    ]
  }
}
```

```json
{
  "dns": {
    "servers": [
      {
        "type": "tls",
        "server": "1.1.1.1"
      }
    ]
  }
}
```

--------------------------------

### Configure Shadowsocks server in sing-box

Source: https://github.com/sagernet/sing-box/blob/testing/docs/manual/proxy-protocol/shadowsocks.md

JSON configuration examples for setting up a Shadowsocks inbound server. Supports both single-user and multi-user authentication modes with multiplexing enabled.

```json
{
  "inbounds": [
    {
      "type": "shadowsocks",
      "listen": "::",
      "listen_port": 8080,
      "network": "tcp",
      "method": "2022-blake3-aes-128-gcm",
      "password": "<password>",
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

```json
{
  "inbounds": [
    {
      "type": "shadowsocks",
      "listen": "::",
      "listen_port": 8080,
      "network": "tcp",
      "method": "2022-blake3-aes-128-gcm",
      "password": "<server_password>",
      "users": [
        {
          "name": "sekai",
          "password": "<user_password>"
        }
      ],
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

--------------------------------

### Compile Rule Set JSON to Binary

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/rule-set/source-format.md

Use this command to compile a JSON rule set file into a binary rule-set file (.srs). The output file name can be specified.

```bash
sing-box rule-set compile [--output <file-name>.srs] <file-name>.json
```

--------------------------------

### Connection Timeout Duration

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/shared/dial.md

Set the connection timeout using Go's Duration format. Examples include '300ms', '-1.5h', or '2h45m'. Valid units are ns, us, ms, s, m, h.

```json
{
  "connect_timeout": "30s"
}
```

--------------------------------

### Configure Trojan outbound with TLS settings

Source: https://github.com/sagernet/sing-box/blob/testing/docs/manual/proxy-protocol/trojan.md

Examples of configuring a Trojan outbound proxy in sing-box. These snippets demonstrate how to handle standard TLS, self-signed certificates via path, and insecure certificate verification.

```json
{
  "outbounds": [
    {
      "type": "trojan",
      "server": "127.0.0.1",
      "server_port": 8080,
      "password": "password",
      "tls": {
        "enabled": true,
        "server_name": "example.org"
      },
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

```json
{
  "outbounds": [
    {
      "type": "trojan",
      "server": "127.0.0.1",
      "server_port": 8080,
      "password": "password",
      "tls": {
        "enabled": true,
        "server_name": "example.org",
        "certificate_path": "/path/to/certificate.pem"
      },
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

```json
{
  "outbounds": [
    {
      "type": "trojan",
      "server": "127.0.0.1",
      "server_port": 8080,
      "password": "password",
      "tls": {
        "enabled": true,
        "server_name": "example.org",
        "insecure": true
      },
      "multiplex": {
        "enabled": true
      }
    }
  ]
}
```

--------------------------------

### OCM Client Configuration Example (TOML)

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/service/ocm.md

TOML configuration for a client to connect to an OCM service, setting the model provider name, base URL, and WebSocket support.

```toml
# profile = "ocm"                # set as default profile

[model_providers.ocm]
name = "OCM Proxy"
base_url = "http://127.0.0.1:8080/v1"
supports_websockets = true

[profiles.ocm]
model_provider = "ocm"
# model = "gpt-5.4"              # if the latest model is not yet publicly released
# model_reasoning_effort = "xhigh"
```

--------------------------------

### Define Predefined Hosts Mappings

Source: https://github.com/sagernet/sing-box/blob/testing/docs/configuration/dns/server/hosts.md

Manually map hostnames to IP addresses within the configuration.

```json
{
  "predefined": {
    "www.google.com": "127.0.0.1",
    "localhost": [
      "127.0.0.1",
      "::1"
    ]
  }
}
```