sing-box

https://sing-box.sagernet.org/configuration/
Admin
sing-box is a universal proxy platform that provides flexible network routing, DNS management, and...
Tokens:81,007
Snippets:1,294
Trust Score:4
Update:1 month ago
Show doc for...
Tokens:
Raw
### DERP config_path Example

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

Example value for the required config_path field.

```text
derper.key
```

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

### CCM client example

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

Client-side setup for using the CCM service. Sets the base URL to the local server and the auth token to a user's token, then launches the Claude Code CLI.

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

claude

```

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

### Tailscale state_directory example

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

Example value for the directory where the Tailscale state is stored.

```text
$HOME/.tailscale
```

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

### Clash API with external UI (since 1.10.0)

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

Example configuration since sing-box 1.10.0 showing external UI setup with a commented download detour. Use when serving a static UI from the Clash API.

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

```

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

### Tailscale hostname example

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

Example value for the hostname of the node.

```text
localhost
```

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

### Tailscale advertise_routes example

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

Example value for CIDR prefixes to advertise into the Tailscale network.

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

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

### Accept pushed default resolvers example

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

Example for accepting pushed default resolvers and search domains. Enables both accept_default_resolvers and accept_search_domain to use the VPN-pushed settings for unmatched and single-label queries.

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

```

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

### Route Rule Configuration Structure

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

Example configuration showing the structure of route rules, including various matching fields and a logical rule example.

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

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

### OpenVPN DNS server example with routing rules

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

Example configuration that combines a local DNS server and an OpenVPN DNS server, with a routing rule to prefer the OpenVPN server for matching queries. The final fallback is the local server.

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

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

### Tailscale advertise_tags example

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

Example value for tags to advertise for this node.

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

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

### Use hosts if available (sing-box < 1.14.0)

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

Example for sing-box versions before 1.14.0: uses the hosts server by adding a rule with ip_accept_any and server. The first server entry is abbreviated with ... as a placeholder.

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

```

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

### CCM server example

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

Example server configuration for the CCM service. Listens on 0.0.0.0:8080, enables usage tracking to ./claude-usages.json, and defines two 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"
        }
      ]
    }
  ]
}

```

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

### path field example

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

Configures the path field with a list of hosts files. The commented line shows the default single-file form; the active example uses an array. On Windows the default is C:\Windows\System32\Drivers\etc\hosts.

```json
{
  // "path": "/etc/hosts"

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

```

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

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

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

Example for split DNS using the Resolved server for sing-box versions before 1.14.0. Uses 'ip_accept_any' rule to route all queries to the 'resolved' server.

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

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

### Split DNS only example

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

Example for split DNS only: routes only the pushed split-DNS rules through the OpenConnect server, while unmatched queries go to the local server. Uses a routing rule with preferred_by and action route.

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

```

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

### Tun Inbound Configuration Structure

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

A comprehensive example of the tun inbound configuration object, showcasing available fields and 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_tproxy_mark": "0x2026",
  "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
}
```

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

### Use hosts if available (sing-box 1.14.0+)

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

Example for sing-box 1.14.0 and later: uses the hosts server when available by adding a rule with preferred_by and action route. The first server entry is abbreviated with ... as a placeholder.

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

```

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

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

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

Example for split DNS using the Resolved server as the preferred server. Requires sing-box 1.14.0 or later. The 'preferred_by' rule routes queries to the 'resolved' server.

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

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

### SSM API servers field example

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

Example of the 'servers' field mapping the HTTP endpoint '/' to the Shadowsocks inbound tag 'ss-in'. The selected inbound must have 'managed' enabled.

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

```

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

### Log configuration structure

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

Example configuration for the log section. Set disabled to true to disable logging, level to one of trace, debug, info, warn, error, fatal, or panic, output to a file path to write logs there instead of the console, and timestamp to true to add time to each line.

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

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

### HTTP Outbound Configuration Example

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

JSON structure for configuring the `http` outbound. Required fields are `server` and `server_port`. Optional fields include `username`, `password`, `path`, `headers`, `tls`, and Dial Fields.

```json
{
  "type": "http",
  "tag": "http-out",

  "server": "127.0.0.1",
  "server_port": 1080,
  "username": "sekai",
  "password": "admin",
  "path": "",
  "headers": {},
  "tls": {},

  ... // Dial Fields
}
```

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

### QUIC Fields structure

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

JSON example of QUIC fields configuration. Includes initial_packet_size to set initial QUIC packet size, and disable_path_mtu_discovery to control QUIC path MTU discovery. Referenced from sing-box docs.

```json
{
  "initial_packet_size": 0,
  "disable_path_mtu_discovery": false,

  ... // HTTP2 Fields
}

```

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

### MagicDNS only as global DNS with 'ip_accept_any' (sing-box < 1.14.0)

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

Alternative configuration for sing-box versions before 1.14.0. It uses the same server setup but the rule uses 'ip_accept_any': true instead of the 'preferred_by'/'action' fields to route all queries to the Tailscale server.

```json
{
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      },
      {
        "type": "tailscale",
        "tag": "ts",
        "endpoint": "ts-ep"
      }
    ],
    "rules": [
      {
        "ip_accept_any": true,
        "server": "ts"
      }
    ]
  }
}

```

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

### verify_client_url String Shortcut

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

Shortcut configuration for verify_client_url using a string.

```json
{ "url": __URL__ }
```

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

### Check Configuration Syntax

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

Command to validate the syntax of a sing-box configuration file.

```bash
sing-box check
```

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

### predefined field example

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

Defines predefined hosts mappings. A domain can map to a single IP string or to an array of IPs (IPv4 and IPv6).

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

```

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

### Basic OCM Client Configuration

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

Client configuration for connecting to an OCM proxy, followed by the command to run the client.

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

```bash
codex --profile ocm
```

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

### UDP NAT Configuration Structure

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

Example JSON structure for configuring UDP NAT fields in sing-box. Includes udp_timeout, udp_mapping, udp_filtering, and udp_nat_max.

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

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

### Format Configuration File

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

Command to format a configuration file or directory in-place.

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

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

### WireGuard outbound configuration structure

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

Example JSON configuration for the WireGuard outbound. Includes server, local_address, private_key, peers, and other fields. Note that this outbound is deprecated in sing-box 1.11.0 and will be removed in 1.13.0.

```json
{
  "type": "wireguard",
  "tag": "wireguard-out",

  "server": "127.0.0.1",
  "server_port": 1080,
  "system_interface": false,
  "interface_name": "wg0",
  "local_address": [
    "10.0.0.1/32"
  ],
  "private_key": "YNXtAzepDqRv9H52osJVDQnznT5AM11eCK3ESpwSt04=",
  "peers": [
    {
      "server": "127.0.0.1",
      "server_port": 1080,
      "public_key": "Z1XXLsKYkYxuiYjJIkRvtIKFepCYHTgON+GwPq7SOV4=",
      "pre_shared_key": "31aIhAPwktDGpH4JDhA8GNvjFXEf/a6+UaQRyOAiyfM=",
      "allowed_ips": [
        "0.0.0.0/0"
      ],
      "reserved": [0, 0, 0]
    }
  ],
  "peer_public_key": "Z1XXLsKYkYxuiYjJIkRvtIKFepCYHTgON+GwPq7SOV4=",
  "pre_shared_key": "31aIhAPwktDGpH4JDhA8GNvjFXEf/a6+UaQRyOAiyfM=",
  "reserved": [0, 0, 0],
  "workers": 4,
  "mtu": 1408,
  "network": "tcp",

  // Deprecated

  "gso": false,

  ... // Dial Fields
}
```

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

### ShadowTLS inbound configuration structure

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

Example JSON structure for the ShadowTLS inbound. The 'handshake' field is required, and 'handshake_for_server_name' is only available in protocol versions 2/3. The 'wildcard_sni' field is available since sing-box 1.12.0.

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

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

### TProxy Inbound Configuration Structure

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

Shows the JSON structure for a TProxy inbound, including the type, tag, listen fields, network, and UDP NAT fields. The network field is set to 'udp' in this example.

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

  ... // Listen Fields

  "network": "udp",

  ... // UDP NAT Fields
}
```

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

### Enter namespace with nsenter

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

Commands to enter the namespace using the PID written to the pid_file. Use the root command when sing-box is running as root, or the alternative command for unprivileged operation.

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

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

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

### predefined action configuration

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

The predefined action responds with custom, hardcoded DNS records.

```json
{
  "action": "predefined",
  "rcode": "",
  "answer": [],
  "ns": [],
  "extra": []
}
```

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

### Basic OCM Server Configuration

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

A minimal server configuration for the OCM service.

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

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

### Headless rule JSON structure

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

Shows the JSON structure of a headless rule, including all available fields and their types. The rule can be a single object or an array of rule objects. The example includes a logical rule with mode 'and'.

```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
    }
  ]
}
```
Tokens:
Raw