### 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 -n ``` ```bash nsenter -t -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 } ] } ```