### Install Sing-box on FreeBSD (FreshPorts)

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

Install sing-box using pkg on FreeBSD.

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

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

### Install Sing-box on Windows with winget

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

Use winget to install sing-box on Windows.

```powershell
winget install sing-box
```

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

### Install Sing-box on NixOS (nixpkgs)

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

Install sing-box using nix-env on NixOS.

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

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

### Install Sing-box on Windows with Scoop

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

Use Scoop to install sing-box on Windows.

```powershell
scoop install sing-box
```

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

### Build and Install sing-box

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

Execute this command to build the sing-box application and install the binary to your Go binary directory.

```bash
make install
```

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

### Manual Installation Script

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

Downloads and installs the latest sing-box package from GitHub releases using a shell script. Supports beta and specific version installations.

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

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

### Install sing-box on Debian/APT

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

Adds the sing-box repository and installs the package using APT. Use 'sing-box-beta' for the beta version.

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

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

### Example Clash API Configuration (Download)

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

Example configuration for serving external UI via download. Specifies the controller address and the UI type.

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

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

### Install sing-box via Universal Script

Source: https://context7.com/ref1nd/sing-box/llms.txt

Installs the latest stable or beta version of sing-box using a curl-based installation script. Specify --beta for beta versions or --version for a specific release.

```bash
# Universal install script (latest stable)
curl -fsSL https://sing-box.app/install.sh | sh
```

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

```bash
# Specific version
curl -fsSL https://sing-box.app/install.sh | sh -s -- --version 1.13.12
```

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

### Install Sing-box on Windows with Chocolatey

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

Install sing-box using Chocolatey on Windows.

```powershell
choco install sing-box
```

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

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

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

Adds the sing-box repository and installs the package using DNF 5. Use 'sing-box-beta' for the beta version.

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

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

### Install Sing-box on AOSC (DEB)

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

Install sing-box using apt on AOSC.

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

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

### Install Sing-box with Homebrew on macOS/Linux

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

Use Homebrew to install sing-box on macOS or Linux systems.

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

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

### Install Sing-box on Arch Linux (AUR)

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

Use the AUR helper to install sing-box on Arch Linux.

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

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

### CCM Server Configuration Example

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

An example of how to configure the CCM service on the server side, including listen address, port, usage tracking path, 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"
        }
      ]
    }
  ]
}
```

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

### Install Sing-box on Android (Termux)

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

Install sing-box using pkg on Termux for Android.

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

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

### Install Sing-box on Alpine Linux (APK)

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

Install sing-box using the apk package manager on Alpine Linux.

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

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

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

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

Adds the sing-box repository and installs the package using DNF 4. Requires 'dnf-plugins-core'. Use 'sing-box-beta' for the beta version.

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

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

### CCM Client Configuration Example

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

Demonstrates how to configure the client to connect to the CCM service. This involves setting the ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN environment variables.

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

claude
```

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

### Install sing-box via APT Repository

Source: https://context7.com/ref1nd/sing-box/llms.txt

Installs sing-box on Debian/Ubuntu systems using the official APT repository. Ensure the GPG key is added and the repository is configured.

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

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

### Mixed Inbound Configuration Example

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

Basic configuration for a mixed inbound, including user credentials and system proxy settings.

```json
{
  "type": "mixed",
  "tag": "mixed-in",

  ... // Listen Fields

  "users": [
    {
      "username": "admin",
      "password": "admin"
    }
  ],
  "set_system_proxy": false
}
```

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

### Full Route Rule Example

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

This example demonstrates a comprehensive route rule with various matching conditions and actions. It covers inbound, IP version, network, authentication, protocol, client, domain matching, geoIP/geosite, IP CIDR, port, process, package name, user, network type, interface address, and preferred by. It also includes deprecated fields.

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

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

### Run sing-box with Configuration Files

Source: https://context7.com/ref1nd/sing-box/llms.txt

Starts the sing-box service using one or more configuration files. Supports single files, merged files, and configurations from a directory.

```bash
# Run with a single config file
sing-box run -c /etc/sing-box/config.json
```

```bash
# Run with multiple config files (merged)
sing-box run -c base.json -c extra.json
```

```bash
# Run configs from a directory
sing-box run -C /etc/sing-box/conf.d/
```

```bash
# Run with a specific working directory and disable color
sing-box run -D /var/lib/sing-box --disable-color -c config.json
```

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

### OCM Client Configuration Example

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

Illustrates how to configure a client to use the OCM proxy. This involves setting up the model provider and profile in the client's TOML configuration.

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

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

### Example Tailscale Advertise Routes

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

Configure CIDR prefixes to advertise into the Tailscale network as reachable through the current node.

```json
["192.168.1.1/24"]
```

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

### Install sing-box via Package Managers

Source: https://context7.com/ref1nd/sing-box/llms.txt

Installs sing-box using common package managers like Homebrew for macOS/Linux, Scoop for Windows, and AUR for Arch Linux.

```bash
# Homebrew (macOS / Linux)
brew install sing-box
```

```bash
# Scoop (Windows)
scoop install sing-box
```

```bash
# Arch Linux AUR
yay -S sing-box
```

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

### Trojan Inbound Configuration Example

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

This is a basic example of a Trojan inbound configuration. It includes user credentials and fallback settings.

```json
{
  "type": "trojan",
  "tag": "trojan-in",

  ... // Listen Fields

  "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": {}
}
```

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

### Example Clash API Configuration (Online)

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

Example configuration for the Clash API, enabling access control for origins and private networks. Useful for integrating with web interfaces.

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

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

### Install sing-box via Homebrew Cask

Source: https://github.com/ref1nd/sing-box/blob/testing/docs/clients/apple/index.md

Use this command to install the standalone macOS version of sing-box if you are using Homebrew.

```bash
# brew install sfm
```

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

### TUN Inbound Configuration Example

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

A comprehensive example of a TUN inbound configuration, demonstrating various settings for IP addresses, MTU, DNS, routing, and interface filtering. This configuration is supported on Linux, Windows, and macOS.

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

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

### OCM Server Basic Configuration

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

Example of a basic OCM server configuration, specifying the service type and listen address and port.

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

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

### ShadowTLS Configuration Structure

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

A comprehensive example of a ShadowTLS inbound configuration, demonstrating various fields and their typical usage.

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

  ... // Listen Fields

  "version": 3,
  "password": "fuck me till the daylight",
  "users": [
    {
      "name": "sekai",
      "password": "8JCsPssfgS8tiRwiMlhARg=="
    }
  ],
  "handshake": {
    "server": "google.com",
    "server_port": 443,
    
    ... // Dial Fields
  },
  "handshake_for_server_name": {
    "example.com": {
      "server": "example.com",
      "server_port": 443,

      ... // Dial Fields
    }
  },
  "strict_mode": false,
  "wildcard_sni": ""
}
```

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

### TUIC Outbound Configuration Example

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

This is a basic example of a TUIC outbound configuration. Ensure all required fields like server, server_port, uuid, and tls are provided.

```json
{
  "type": "tuic",
  "tag": "tuic-out",
  
  "server": "127.0.0.1",
  "server_port": 1080,
  "uuid": "2DD61D93-75D8-4DA4-AC0E-6AECE7EAC365",
  "password": "hello",
  "congestion_control": "cubic",
  "udp_relay_mode": "native",
  "udp_over_stream": false,
  "zero_rtt_handshake": false,
  "heartbeat": "10s",
  "network": "tcp",
  "tls": {},

  ... // QUIC Fields

  ... // Dial Fields
}
```

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

### OCM Server Configuration with Authentication

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

An example of an OCM server configuration that includes usage tracking and user authentication with custom tokens.

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

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

### DNS Rule Structure Example

Source: https://github.com/ref1nd/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.

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

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

### Run Sing-box with Docker Compose

Source: https://github.com/ref1nd/sing-box/blob/testing/docs/installation/docker.md

Define and run the Sing-box service using Docker Compose. This configuration automates the setup, including volume mounting and restart policies.

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

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

### TUIC Inbound Configuration Example

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

This JSON snippet shows a basic configuration for a TUIC inbound server, including user credentials and network parameters. Ensure TLS is configured separately.

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

  "users": [
    {
      "name": "sekai",
      "uuid": "059032A9-7D40-4A96-9BB1-36823D848068",
      "password": "hello"
    }
  ],
  "congestion_control": "cubic",
  "auth_timeout": "3s",
  "zero_rtt_handshake": false,
  "heartbeat": "10s",
  "tls": {},

  ... // QUIC Fields
}
```

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

### Manage Sing-box Service with systemd

Source: https://context7.com/ref1nd/sing-box/llms.txt

These bash commands are used to manage the sing-box service on a Linux system using systemd. Ensure sing-box is installed and configured before enabling and starting the service.

```bash
# Enable and start sing-box as a system service
sudo systemctl enable sing-box
sudo systemctl start sing-box
```

```bash
# View live logs
sudo journalctl -u sing-box --output cat -f
```

```bash
# Check status
sudo systemctl status sing-box
```

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

### Simple Build sing-box

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

Use this command to perform a basic build of the sing-box application.

```bash
make
```

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

### Build sing-box from Source with Custom Tags

Source: https://context7.com/ref1nd/sing-box/llms.txt

Builds sing-box from source using Go build tags to enable/disable features. The Makefile simplifies the process, but direct `go build` is also shown.

```bash
# Simple build (uses Makefile with all default tags)
make
```

```bash
# Build and install to $GOBIN
make install
```

```bash
# Custom build — enable only specific tags
TAGS="with_quic with_wireguard with_clash_api with_gvisor" make
```

```bash
# Equivalent direct go build
go build -tags "with_quic with_wireguard with_clash_api with_gvisor" \
  -ldflags "-X 'internal/godebug.defaultGODEBUG=multipathtcp=0' -checklinkname=0" \
  ./cmd/sing-box
```

```bash
# Build with standard gRPC and V2Ray API (both off by default)
TAGS="with_grpc with_v2ray_api" make
```

```bash
# Build with embedded Tor support (requires CGO)
TAGS="with_embedded_tor" make
```

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

### Basic Log Configuration

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

Example of a basic log configuration block. Set 'disabled' to false to enable logging, specify the 'level' (e.g., 'info'), an 'output' file path, and whether to include 'timestamp'.

```json
{
  "log": {
    "disabled": false,
    "level": "info",
    "output": "box.log",
    "timestamp": true
  }
}
```

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

### Sing-box Rule Set Structure Example

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

This JSON structure demonstrates the various fields available for defining rules in sing-box. It includes examples for domain matching, IP/CIDR, ports, process information, network types, and more.

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

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

### Full Client Configuration with TUN and Rule-set Routing

Source: https://context7.com/ref1nd/sing-box/llms.txt

This JSON configuration sets up a sing-box client with TUN transparent proxy, rule-set routing, and automatic latency selection. It requires careful setup of DNS, inbounds, outbounds, and routing rules for optimal performance.

```json
{
  "log": {
    "level": "info",
    "timestamp": true
  },
  "dns": {
    "servers": [
      {
        "tag": "remote",
        "address": "tls://8.8.8.8",
        "strategy": "prefer_ipv4",
        "detour": "select"
      },
      {
        "tag": "local",
        "address": "https://223.5.5.5/dns-query",
        "strategy": "prefer_ipv4",
        "detour": "direct"
      },
      {
        "tag": "fakeip",
        "address": "fakeip"
      }
    ],
    "rules": [
      { "rule_set": ["geosite-cn"], "server": "local" },
      { "query_type": ["A", "AAAA"], "server": "fakeip" }
    ],
    "final": "remote",
    "reverse_mapping": true,
    "fakeip": {
      "enabled": true,
      "inet4_range": "198.18.0.0/15",
      "inet6_range": "fc00::/18"
    }
  },
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "address": ["172.18.0.1/30", "fdfe:dcba:9876::1/126"],
      "mtu": 9000,
      "auto_route": true,
      "auto_redirect": true,
      "strict_route": true,
      "stack": "mixed"
    }
  ],
  "outbounds": [
    {
      "type": "selector",
      "tag": "select",
      "outbounds": ["auto", "proxy-hk", "proxy-us"],
      "default": "auto"
    },
    {
      "type": "urltest",
      "tag": "auto",
      "outbounds": ["proxy-hk", "proxy-us"],
      "interval": "3m",
      "tolerance": 50
    },
    {
      "type": "shadowsocks",
      "tag": "proxy-hk",
      "server": "hk.example.com",
      "server_port": 8388,
      "method": "2022-blake3-aes-128-gcm",
      "password": "8JCsPssfgS8tiRwiMlhARg=="
    },
    {
      "type": "hysteria2",
      "tag": "proxy-us",
      "server": "us.example.com",
      "server_port": 443,
      "password": "hy2_password",
      "tls": { "enabled": true, "server_name": "us.example.com" }
    },
    { "type": "direct", "tag": "direct" },
    { "type": "block", "tag": "block" },
    { "type": "dns", "tag": "dns-out" }
  ],
  "route": {
    "rules": [
      { "protocol": "dns", "action": "route", "outbound": "dns-out" },
      { "ip_is_private": true, "action": "route", "outbound": "direct" },
      { "rule_set": ["geosite-ads"], "action": "reject" },
      { "rule_set": ["geoip-cn", "geosite-cn"], "action": "route", "outbound": "direct" }
    ],
    "rule_set": [
      {
        "type": "remote",
        "tag": "geoip-cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs",
        "update_interval": "1d"
      },
      {
        "type": "remote",
        "tag": "geosite-cn",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs",
        "update_interval": "1d"
      },
      {
        "type": "remote",
        "tag": "geosite-ads",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-category-ads-all.srs",
        "update_interval": "1d"
      }
    ],
    "final": "select",
    "auto_detect_interface": true
  },
  "experimental": {
    "cache_file": {
      "enabled": true,
      "store_fakeip": true,
      "store_dns": true
    },
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "secret": "my_secret"
    }
  }
}
```

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

### Inbound TLS Configuration Example

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

Configure TLS settings for inbound connections. This includes enabling TLS, setting server name, ALPN, minimum/maximum TLS versions, cipher suites, certificate paths, 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"
  }
}
```

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

### Example Tailscale Advertise Tags

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

Specify tags for this node, used for ACL enforcement purposes. This feature is available since sing-box 1.13.0.

```json
["tag:server"]
```

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

### Basic TUN Usage (IPv4 & IPv6)

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

Configure TUN inbound for both IPv4 and IPv6 DNS resolution. This setup supports dual-stack networking.

```json
{
  "dns": {
    "servers": [
      {
        "tag": "google",
        "type": "tls",
        "server": "8.8.8.8"
      },
      {
        "tag": "local",
        "type": "udp",
        "server": "223.5.5.5"
      }
    ]
  },
  "inbounds": [
    {
      "type": "tun",
      "address": ["172.19.0.1/30", "fdfe:dcba:9876::1/126"],
      "auto_route": true,
      // "auto_redirect": true, // On linux
      "strict_route": true
    }
  ],
  "outbounds": [
    // ...
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "action": "sniff"
      },
      {
        "protocol": "dns",
        "action": "hijack-dns"
      },
      {
        "ip_is_private": true,
        "outbound": "direct"
      }
    ],
    "default_domain_resolver": "local",
    "auto_detect_interface": true
  }
}
```

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

### Merge Sing-box Configurations

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

Combines multiple configuration files or configurations from a directory into a single output file. Useful for managing complex setups.

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

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

### Generate WireGuard Keys

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

Use the `wg` utility or `sing-box generate wg-keypair` to create private and public keys for WireGuard.

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

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

### VLESS Outbound with Reality

Source: https://context7.com/ref1nd/sing-box/llms.txt

Connects to a VLESS server using XTLS Vision flow and Reality for anti-detection. Requires specific server-side setup for Reality.

```json
{
  "outbounds": [
    {
      "type": "vless",
      "tag": "vless-out",
      "server": "198.51.100.1",
      "server_port": 443,
      "uuid": "bf000d23-0752-40b4-affe-68f7707a9661",
      "flow": "xtls-rprx-vision",
      "tls": {
        "enabled": true,
        "server_name": "example.com",
        "reality": {
          "enabled": true,
          "public_key": "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0",
          "short_id": "0123456789abcdef"
        }
      }
    }
  ]
}
```

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

### Validate sing-box Configuration

Source: https://context7.com/ref1nd/sing-box/llms.txt

Checks the syntax and validity of a sing-box configuration file without starting the service. Exits with a non-zero status code on error.

```bash
sing-box check -c /etc/sing-box/config.json
```