sing-box

https://sing-box.sagernet.org
Admin
sing-box is a universal proxy platform supporting a wide range of proxy protocols and routing...
Tokens:155,143
Snippets:1,264
Trust Score:4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Build and install binary

Source: https://sing-box.sagernet.org/installation/build-from-source

Compiles the project and installs the resulting binary into the $GOBIN directory.

```makefile
make install

```

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

### Install sing-box via winget (Windows)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on Windows using winget.

```bash
winget install sing-box
```

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

### Start systemd service

Source: https://sing-box.sagernet.org/installation/package-manager

Starts the sing-box service.

```bash
sudo systemctl start sing-box
```

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

### Install sing-box via pkg (FreeBSD)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on FreeBSD using pkg.

```bash
pkg install sing-box
```

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

### Install sing-box via nixpkgs

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on NixOS using nix-env.

```bash
nix-env -iA nixos.sing-box
```

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

### Install sing-box via Scoop (Windows)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on Windows using Scoop.

```bash
scoop install sing-box
```

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

### OpenConnect DNS Server Usage Examples

Source: https://sing-box.sagernet.org/configuration/dns/server/openconnect

Examples demonstrating split DNS routing and accepting pushed default resolvers.

```json
{
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      },
      {
        "type": "openconnect",
        "tag": "oc",
        "endpoint": "oc-client"
      }
    ],
    "rules": [
      {
        "preferred_by": "oc",
        "action": "route",
        "server": "oc"
      }
    ],
    "final": "local"
  }
}
```

```json
{
  "dns": {
    "servers": [
      {
        "type": "openconnect",
        "endpoint": "oc-client",
        "accept_default_resolvers": true,
        "accept_search_domain": true
      }
    ]
  }
}
```

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

### Manual Installation Script

Source: https://sing-box.sagernet.org/installation/package-manager

Downloads and installs the latest sing-box package from GitHub releases using a script.

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

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

### OpenVPN DNS Server Example

Source: https://sing-box.sagernet.org/configuration/dns/server/openvpn

Complete configuration example demonstrating an OpenVPN DNS server integrated with local DNS and routing rules.

```json
{
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      },
      {
        "type": "openvpn",
        "tag": "ovpn-dns",
        "endpoint": "ovpn-client",
        "accept_default_resolvers": true,
        "accept_search_domain": true
      }
    ],
    "rules": [
      {
        "preferred_by": "ovpn-dns",
        "action": "route",
        "server": "ovpn-dns"
      }
    ],
    "final": "local"
  }
}
```

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

### Manual Installation Script (Beta)

Source: https://sing-box.sagernet.org/installation/package-manager

Downloads and installs the latest beta version of sing-box from GitHub releases using a script.

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

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

### Install sing-box on Debian/APT

Source: https://sing-box.sagernet.org/installation/package-manager

Adds the sing-box repository and installs the package using APT.

```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 via Chocolatey (Windows)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on Windows using Chocolatey.

```bash
choco install sing-box
```

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

### Manual Installation Script (Specific Version)

Source: https://sing-box.sagernet.org/installation/package-manager

Downloads and installs a specific version of sing-box from GitHub releases using a script.

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

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

### Install sing-box via APK (Alpine)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on Alpine Linux using apk.

```bash
apk add sing-box
```

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

### Install sing-box via Homebrew (macOS/Linux)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on macOS or Linux using Homebrew.

```bash
brew install sing-box
```

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

### Install sing-box via APT (AOSC)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on AOSC using apt.

```bash
apt install sing-box
```

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

### Configure Shadowsocks Server

Source: https://sing-box.sagernet.org/manual/proxy-protocol/shadowsocks

Configuration examples for setting up a Shadowsocks server in single-user or multi-user mode.

```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
      }
    }
  ]
}
```

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

### Install sing-box via pkg (Termux/Android)

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on Android via Termux using pkg.

```bash
pkg add sing-box
```

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

### DNS Rules Configuration Example

Source: https://sing-box.sagernet.org/migration

Illustrates how to define DNS routing rules based on domains and client subnets.

```json
{
  "domain": "google.com",
  "server": "google",
  "client_subnet": "1.1.1.1"
}
```

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

### Install sing-box on Redhat/DNF 5

Source: https://sing-box.sagernet.org/installation/package-manager

Adds the sing-box repository and installs the package using DNF 5.

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

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

### DNS Rule Configuration Structure

Source: https://sing-box.sagernet.org/configuration/dns/rule

Example configuration showing the full range of available DNS rule matchers and action settings.

```json
{
  "dns": {
    "rules": [
      {
        "inbound": [
          "mixed-in"
        ],
        "ip_version": 6,
        "query_type": [
          "A",
          "HTTPS",
          32768
        ],
        "query_client_subnet": [
          "10.0.0.0/24",
          "192.168.0.1"
        ],
        "query_dnssec": false,
        "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",

        // Deprecated

        "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"
      }
    ]
  }
}
```

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

### CCM Server Configuration Example

Source: https://sing-box.sagernet.org/configuration/service/ccm

An example of a CCM service configuration for a server, demonstrating how to set listen ports, usage tracking paths, and authorized users with their tokens.

```json
{
  "services": [
    {
      "type": "ccm",
      "listen": "0.0.0.0",
      "listen_port": 8080,
      "usages_path": "./claude-usages.json",
      "users": [
        {
          "name": "alice",
          "token": "ak-ccm-hello-world"
        },
        {
          "name": "bob",
          "token": "ak-ccm-hello-bob"
        }
      ]
    }
  ]
}

```

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

### Enable systemd service

Source: https://sing-box.sagernet.org/installation/package-manager

Enables the sing-box service to start on boot.

```bash
sudo systemctl enable sing-box
```

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

### Install sing-box via AUR

Source: https://sing-box.sagernet.org/installation/package-manager

Installs sing-box on Arch Linux using the AUR helper.

```bash
? -S sing-box
```

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

### Install sing-box on Redhat/DNF 4

Source: https://sing-box.sagernet.org/installation/package-manager

Adds the sing-box repository and installs the package using DNF 4.

```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
```

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

### Configure Shadowsocks Client

Source: https://sing-box.sagernet.org/manual/proxy-protocol/shadowsocks

Configuration examples for connecting to a Shadowsocks server as a client in single-user or multi-user mode.

```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
      }
    }
  ]
}
```

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

### CCM Client Configuration Example

Source: https://sing-box.sagernet.org/configuration/service/ccm

Example client-side configuration for connecting to a CCM service. It involves setting environment variables for the base URL and authentication token, followed by invoking the 'claude' command.

```bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"
export ANTHROPIC_AUTH_TOKEN="ak-ccm-hello-world"

claude

```

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

### OCM Server Configuration Example

Source: https://sing-box.sagernet.org/configuration/service/ocm

A basic server configuration for the OCM service, specifying the listen address and port.

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

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

### Install macOS standalone version via Homebrew

Source: https://sing-box.sagernet.org/clients/apple

Use this command to install the sing-box macOS standalone application using Homebrew.

```bash
# brew install sfm
```

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

### Headless Rule Structure Example

Source: https://sing-box.sagernet.org/configuration/rule-set/headless-rule

This snippet shows the comprehensive structure of a headless rule, demonstrating the various fields available for matching network traffic. It includes examples for query types, domains, IP addresses, ports, process information, package names, and network conditions.

```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
    }
  ]
}
```

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

### Route Rule Configuration Structure

Source: https://sing-box.sagernet.org/configuration/route/rule

A comprehensive example showing all available fields for defining routing rules, including standard matchers and logical rule types.

```json
{
  "route": {
    "rules": [
      {
        "inbound": [
          "mixed-in"
        ],
        "ip_version": 6,
        "network": [
          "tcp"
        ],
        "auth_user": [
          "usera",
          "userb"
        ],
        "protocol": [
          "tls",
          "http",
          "quic"
        ],
        "client": [
          "chromium",
          "safari",
          "firefox",
          "quic-go"
        ],
        "domain": [
          "test.com"
        ],
        "domain_suffix": [
          ".cn"
        ],
        "domain_keyword": [
          "test"
        ],
        "domain_regex": [
          "^stun\\..+"
        ],
        "geosite": [
          "cn"
        ],
        "source_geoip": [
          "private"
        ],
        "geoip": [
          "cn"
        ],
        "source_ip_cidr": [
          "10.0.0.0/24",
          "192.168.0.1"
        ],
        "source_ip_is_private": false,
        "ip_cidr": [
          "10.0.0.0/24",
          "192.168.0.1"
        ],
        "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"
        ],
        "wifi_ssid": [
          "My WIFI"
        ],
        "wifi_bssid": [
          "00:00:00:00:00:00"
        ],
        "preferred_by": [
          "tailscale",
          "wireguard"
        ],
        "source_mac_address": [
          "00:11:22:33:44:55"
        ],
        "source_hostname": [
          "my-device"
        ],
        "rule_set": [
          "geoip-cn",
          "geosite-cn"
        ],
        // deprecated
        "rule_set_ipcidr_match_source": false,
        "rule_set_ip_cidr_match_source": false,
        "invert": false,
        "action": "route",
        "outbound": "direct"
      },
      {
        "type": "logical",
        "mode": "and",
        "rules": [],
        "invert": false,
        "action": "route",
        "outbound": "direct"
      }
    ]
  }
}
```

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

### SSM API Server Mapping Example

Source: https://sing-box.sagernet.org/configuration/service/ssm-api

Example of how to map HTTP endpoints to Shadowsocks Inbound tags within the SSM API configuration. Ensure that the selected Shadowsocks inbounds are configured with 'managed' enabled.

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

```

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

### OCM Client Configuration Example

Source: https://sing-box.sagernet.org/configuration/service/ocm

Client-side configuration for connecting to an OCM service using the codex CLI. It sets up a model provider and a profile pointing to the OCM proxy.

```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"

```

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

### Generate Local Schema

Source: https://sing-box.sagernet.org/configuration/schema

Use the CLI to generate a schema file matching the installed binary features.

```bash
sing-box schema -o schema.json
```

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

### Configure Trojan Client Outbound

Source: https://sing-box.sagernet.org/manual/proxy-protocol/trojan

Examples for setting up a Trojan client outbound with standard, self-signed, or insecure certificate verification configurations.

```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
      }
    }
  ]
}
```

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

### Using Hosts with IP Accept Any Rule

Source: https://sing-box.sagernet.org/configuration/dns/server/hosts

An alternative DNS rule configuration that uses the 'hosts' server when 'ip_accept_any' is true. This example is relevant for sing-box versions prior to 1.14.0.

```json
{
  "dns": {
    "servers": [
      {
        "...": "..."
      },
      {
        "type": "hosts",
        "tag": "hosts"
      }
    ],
    "rules": [
      {
        "ip_accept_any": true,
        "server": "hosts"
      }
    ]
  }
}

```

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

### Using Hosts for DNS Routing (sing-box 1.14.0+)

Source: https://sing-box.sagernet.org/configuration/dns/server/hosts

Example of configuring DNS rules to use the 'hosts' server for routing. This is applicable for sing-box versions 1.14.0 and later.

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

```

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

### Configure Trojan Server Inbound

Source: https://sing-box.sagernet.org/manual/proxy-protocol/trojan

Examples for setting up a Trojan server inbound with local certificates, ACME, or ACME with Cloudflare DNS challenge.

```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
      }
    }
  ]
}
```

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

### Rule Set Structure Example

Source: https://sing-box.sagernet.org/configuration/rule-set/source-format

This is the basic JSON structure for a sing-box rule set.

```json
{
  "version": 3,
  "rules": []
}

```

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

### Tun Inbound Configuration Structure

Source: https://sing-box.sagernet.org/configuration/inbound/tun

A comprehensive example of the tun inbound configuration object, including routing, interface, and platform settings.

```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 NAT Fields

  "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": []
    }
  },
  // Deprecated
  "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"
  ],
  ...
  // Listen Fields
}
```

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

### UDP NAT Configuration Structure

Source: https://sing-box.sagernet.org/configuration/shared/udp-nat

Example JSON structure for defining UDP NAT settings in sing-box.

```json
{
  "udp_timeout": "5m",
  "udp_mapping": "endpoint_independent",
  "udp_filtering": "endpoint_independent",
  "udp_nat_max": 0
}
```

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

### Perform a simple build

Source: https://sing-box.sagernet.org/installation/build-from-source

Compiles the project using the default configuration.

```makefile
make

```

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

### Perform a custom build with tags

Source: https://sing-box.sagernet.org/installation/build-from-source

Compiles the project with specific build tags enabled using either make or the go toolchain directly.

```bash
TAGS="tag_a tag_b" make

```

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

```

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

### Disable systemd service

Source: https://sing-box.sagernet.org/installation/package-manager

Disables the sing-box service from starting on boot.

```bash
sudo systemctl disable sing-box
```

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

### Format configuration file

Source: https://sing-box.sagernet.org/configuration

Automatically format the configuration file or directory in-place.

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

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

### Configuring Hosts File Paths

Source: https://sing-box.sagernet.org/configuration/dns/server/hosts

Specifies how to define a list of paths for custom hosts files. Defaults to system paths if not provided.

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

```

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

### Defining Predefined Hosts

Source: https://sing-box.sagernet.org/configuration/dns/server/hosts

Shows how to map hostnames to IP addresses directly within the configuration. Supports single IPs or arrays of IPs for hostnames.

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

```

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

### Validate configuration file

Source: https://sing-box.sagernet.org/configuration

Use this command to verify the syntax and structure of the configuration file.

```bash
sing-box check
```

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

### Migrate DNS Server with Strategy

Source: https://sing-box.sagernet.org/migration

Shows the migration of DNS server strategies from 'ipv4_only' and 'prefer_ipv6' applied directly to servers to being defined in rules or globally.

```json
{
  "dns": {
    "servers": [
      {
        "address": "1.1.1.1",
        "strategy": "ipv4_only"
      },
      {
        "tag": "google",
        "address": "8.8.8.8",
        "strategy": "prefer_ipv6"
      }
    ],
    "rules": [
      {
        "domain": "google.com",
        "server": "google"
      }
    ]
  }
}
```

```json
{
  "dns": {
    "servers": [
      {
        "type": "udp",
        "server": "1.1.1.1"
      },
      {
        "type": "udp",
        "tag": "google",
        "server": "8.8.8.8"
      }
    ],
    "rules": [
      {
        "domain": "google.com",
        "server": "google",
        "strategy": "prefer_ipv6"
      }
    ],
    "strategy": "ipv4_only"
  }
}
```

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

### Server Options Schema

Source: https://sing-box.sagernet.org/schema.json

Defines basic server connectivity parameters including address and port constraints.

```json
"ServerOptions": {
      "type": "object",
      "properties": {
        "server": {
          "type": "string"
        },
        "server_port": {
          "type": "integer",
          "minimum": 0,
          "maximum": 65535
        }
      },
      "additionalProperties": false
    }
```

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

### Enter Namespace via nsenter

Source: https://sing-box.sagernet.org/configuration/network-namespace/unshare

Commands to enter the namespace using the PID file, depending on root privileges.

```bash
nsenter -t <pid> -n
```

```bash
nsenter -t <pid> -U --preserve-credentials -n
```

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

### ShadowTLS Outbound Configuration Structure

Source: https://sing-box.sagernet.org/configuration/outbound/shadowtls

Example structure for configuring a ShadowTLS outbound connection. Ensure 'server', 'server_port', and 'tls' are properly defined. The 'password' field is only available for v2 and v3.

```json
{
  "type": "shadowtls",
  "tag": "st-out",

  "server": "127.0.0.1",
  "server_port": 1080,
  "version": 3,
  "password": "fuck me till the daylight",
  "tls": {},

  ... // Dial Fields
}
```

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

### Clash API Configuration with CORS Enabled

Source: https://sing-box.sagernet.org/configuration/experimental/clash-api

Example configuration enabling CORS for the Clash API, allowing specific origins and private network access. This requires sing-box version 1.10.0 or later.

```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
}
```

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

### Migrate DNS Server with Address Resolver

Source: https://sing-box.sagernet.org/migration

Shows the migration from using 'address_resolver' to a 'domain_resolver' with a separate tagged server configuration.

```json
{
  "dns": {
    "servers": [
      {
        "address": "https://dns.google/dns-query",
        "address_resolver": "google"
      },
      {
        "tag": "google",
        "address": "1.1.1.1"
      }
    ]
  }
}
```

```json
{
  "dns": {
    "servers": [
      {
        "type": "https",
        "server": "dns.google",
        "domain_resolver": "google"
      },
      {
        "type": "udp",
        "tag": "google",
        "server": "1.1.1.1"
      }
    ]
  }
}
```

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

### TCP Brutal Configuration Structure

Source: https://sing-box.sagernet.org/configuration/shared/tcp-brutal

This JSON structure enables TCP Brutal and sets the upload and download bandwidth limits in Mbps. Ensure the 'brutal' congestion control algorithm is installed on your Linux server.

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

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

### View new systemd service logs

Source: https://sing-box.sagernet.org/installation/package-manager

Follows and displays new logs for the sing-box service in real-time.

```bash
sudo journalctl -u sing-box --output cat -f
```

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

### DNS Configuration for Traffic Bypass

Source: https://sing-box.sagernet.org/manual/proxy/client

These configurations define DNS servers and rules to handle geolocation-based resolution. The first example minimizes DNS leaks, while the second includes a client subnet for specific resolution.

```json
{
  "dns": {
    "servers": [
      {
        "tag": "google",
        "type": "tls",
        "server": "8.8.8.8"
      },
      {
        "tag": "local",
        "type": "https",
        "server": "223.5.5.5"
      }
    ],
    "rules": [
      {
        "rule_set": "geosite-geolocation-cn",
        "server": "local"
      },
      {
        "type": "logical",
        "mode": "and",
        "rules": [
          {
            "rule_set": "geosite-geolocation-!cn",
            "invert": true
          },
          {
            "rule_set": "geoip-cn"
          }
        ],
        "server": "local"
      }
    ]
  },
  "route": {
    "default_domain_resolver": "local",
    "rule_set": [
      {
        "type": "remote",
        "tag": "geosite-geolocation-cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-geolocation-cn.srs"
      },
      {
        "type": "remote",
        "tag": "geosite-geolocation-!cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-geolocation-!cn.srs"
      },
      {
        "type": "remote",
        "tag": "geoip-cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs"
      }
    ]
  },
  "experimental": {
    "cache_file": {
      "enabled": true,
      "store_rdrc": true
    },
    "clash_api": {
      "default_mode": "Enhanced"
    }
  }
}
```

```json
{
  "dns": {
    "servers": [
      {
        "tag": "google",
        "type": "tls",
        "server": "8.8.8.8"
      },
      {
        "tag": "local",
        "type": "https",
        "server": "223.5.5.5"
      }
    ],
    "rules": [
      {
        "rule_set": "geosite-geolocation-cn",
        "server": "local"
      },
      {
        "type": "logical",
        "mode": "and",
        "rules": [
          {
            "rule_set": "geosite-geolocation-!cn",
            "invert": true
          },
          {
            "rule_set": "geoip-cn"
          }
        ],
        "server": "google",
        "client_subnet": "114.114.114.114/24" // Any China client IP address
      }
    ]
  },
  "route": {
    "default_domain_resolver": "local",
    "rule_set": [
      {
        "type": "remote",
        "tag": "geosite-geolocation-cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-geolocation-cn.srs"
      },
      {
        "type": "remote",
        "tag": "geosite-geolocation-!cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-geolocation-!cn.srs"
      },
      {
        "type": "remote",
        "tag": "geoip-cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs"
      }
    ]
  },
  "experimental": {
    "cache_file": {
      "enabled": true,
      "store_rdrc": true
    },
    "clash_api": {
      "default_mode": "Enhanced"
    }
  }
}
```

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

### Define Connection and Stream Options

Source: https://sing-box.sagernet.org/schema.json

Schema definitions for connection window sizes, stream concurrency, and packet sizing.

```json
"anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "string"
                            }
                          ]
                        },
                        "connection_receive_window": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "minimum": 0
                            },
                            {
                              "type": "string"
                            }
                          ]
                        },
                        "max_concurrent_streams": {
                          "type": "integer"
                        },
                        "initial_packet_size": {
                          "type": "integer"
                        },
                        "disable_path_mtu_discovery": {
                          "type": "boolean"
                        },
                        "url": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": false
                    }
                  ]
```

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

### Migrate QUIC DNS Server

Source: https://sing-box.sagernet.org/migration

Shows the migration from the deprecated 'address: "quic://1.1.1.1"' format to the new 'type: "quic", "server": "1.1.1.1"' format for QUIC DNS servers.

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

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

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

### Run Sing-box with Docker Command

Source: https://sing-box.sagernet.org/installation/docker

Execute Sing-box in detached mode using a direct Docker run command. Mounts configuration and ensures the container restarts automatically.

```bash
docker run -d \
  -v /etc/sing-box:/etc/sing-box/ \
  --name=sing-box \
  --restart=always \
  ghcr.io/sagernet/sing-box \
  -D /var/lib/sing-box \
  -C /etc/sing-box/ run

```

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

### Define Mesh and STUN Configuration Schema

Source: https://sing-box.sagernet.org/schema.json

Schema definitions for mesh networking options and STUN server settings.

```json
"home": {
  "type": "string"
},
"mesh_with": {
  "anyOf": [
    {
      "$ref": "#/$defs/DERPMeshOptions"
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DERPMeshOptions"
      }
    }
  ]
},
"mesh_psk": {
  "type": "string"
},
"mesh_psk_file": {
  "type": "string"
},
"stun": {
  "anyOf": [
    {
      "type": "integer",
      "minimum": 0,
      "maximum": 65535
    },
    {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "listen": {
          "type": "string"
        },
        "listen_port": {
          "type": "integer",
          "minimum": 0,
          "maximum": 65535
        },
        "bind_interface": {
          "type": "string"
        },
        "routing_mark": {

```

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

### Merge Configuration Files

Source: https://sing-box.sagernet.org/changelog

CLI command to merge multiple configuration files and embed external resources like certificates or keys.

```bash
Merge configurations

Usage:
  sing-box merge [output] [flags]

Flags:
  -h, --help   help for merge

Global Flags:
  -c, --config stringArray             set configuration file path
  -C, --config-directory stringArray   set configuration directory path
  -D, --directory string               set working directory
      --disable-color                  disable color output
```

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

### TUN Platform Options Schema

Source: https://sing-box.sagernet.org/schema.json

Configuration for TUN interface platform-specific settings.

```json
"TunPlatformOptions": {
      "type": "object",
      "properties": {
        "http_proxy": {
          "$ref": "#/$defs/HTTPProxyOptions"
        }
      },
      "additionalProperties": false
    }
```

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

### Split DNS with Resolved Service (IP Accept Any)

Source: https://sing-box.sagernet.org/configuration/dns/server/resolved

An alternative split DNS configuration that uses 'ip_accept_any' to route all queries to the 'resolved' service. This is useful when 'resolved' should handle all DNS traffic.

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

```

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

### Merge configuration files

Source: https://sing-box.sagernet.org/configuration

Combine multiple configuration files or directories into a single output file.

```bash
sing-box merge output.json -c config.json -D config_directory
```

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

### Reference Local JSON Schema

Source: https://sing-box.sagernet.org/configuration/schema

Point the configuration file to a locally generated schema file.

```json
{
  "$schema": "./schema.json"
}
```

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

### Run Sing-box with Docker Compose

Source: https://sing-box.sagernet.org/installation/docker

Define and run Sing-box as a service using Docker Compose. This method simplifies multi-container applications and configuration management.

```yaml
version: "3.8"
services:
  sing-box:
    image: ghcr.io/sagernet/sing-box
    container_name: sing-box
    restart: always
    volumes:
      - /etc/sing-box:/etc/sing-box/
    command: -D /var/lib/sing-box -C /etc/sing-box/ run

```

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

### STUN Server Configuration

Source: https://sing-box.sagernet.org/configuration/service/derp

Options for enabling and configuring a STUN server. This includes listen address, port, and other listen fields.

```json
{
  "enabled": true,

  ... // Listen Fields
}

```

```json
{
  "enabled": true,
  "listen": "",
  "listen_port": "",
  "other Listen Fields": "Listen Fields"
}

```

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

```

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

### USB/IP Server Configuration Structure

Source: https://sing-box.sagernet.org/configuration/service/usbip-server

Basic JSON structure for defining a USB/IP server service.

```json
{
  "type": "usbip-server",

  ... // Listen Fields

  "provider": "",
  "devices": []
}
```

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

### View systemd service logs

Source: https://sing-box.sagernet.org/installation/package-manager

Displays the current logs for the sing-box service.

```bash
sudo journalctl -u sing-box --output cat -e
```

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

### Generate WireGuard Keys

Source: https://sing-box.sagernet.org/configuration/endpoint/wireguard

Commands to generate WireGuard public and private keys using the wg utility.

```bash
wg genkey
echo "private key" || wg pubkey
```

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

### Compile Rule Set Command

Source: https://sing-box.sagernet.org/configuration/rule-set/source-format

Use this command to compile a JSON rule set file into a binary rule-set file (.srs).

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