sing-box Setup Guide: The Universal Proxy Platform

Quick Answer: sing-box is a universal proxy platform — one binary that supports every major proxy protocol. Install: download from GitHub. Configure with a JSON file. It replaces Xray, Hysteria2, and Clash as a single tool for both server and client.

Need a VPS? Vultr (free credit), DigitalOcean ($200 free credit), or RackNerd (cheap annual deals).

What Is sing-box?

sing-box is a universal proxy platform. Instead of running separate software for each protocol (Xray for VLESS, Hysteria binary for Hysteria2, WireGuard for VPN), sing-box handles ALL of them in a single binary with a single config file.

What It Supports

Why sing-box Over Xray?

Use sing-box when: You need Hysteria2 or TUIC on the server, you want one tool for everything, or you want advanced routing rules.

Use Xray/3X-UI when: You want a web panel for managing users (sing-box has no built-in panel), or you're already familiar with Xray configs.

Part 1: Install sing-box

Linux (Server)

# Official install script
bash <(curl -fsSL https://sing-box.app/deb-install.sh)

# Or manual install
# Download latest from https://github.com/SagerNet/sing-box/releases
# Or download manually from https://github.com/SagerNet/sing-box/releases
# and install with: sudo dpkg -i sing-box_VERSION_linux_amd64.deb

# Verify
sing-box version

Config Location

/etc/sing-box/config.json    # Main config file

Start/Stop

sudo systemctl start sing-box
sudo systemctl enable sing-box    # Auto-start on boot
sudo systemctl status sing-box
sudo systemctl restart sing-box

# View logs
sudo journalctl -u sing-box -f

# Test config before applying
sing-box check -c /etc/sing-box/config.json

Part 2: Config Structure

sing-box uses a JSON config file with these main sections:

{
  "log": {},           // Logging settings
  "dns": {},           // DNS resolution
  "inbounds": [],      // How traffic enters (server listeners)
  "outbounds": [],     // How traffic exits (where it goes)
  "route": {}          // Rules for directing traffic
}

Minimal Example (SOCKS5 Proxy)

{
  "inbounds": [
    {
      "type": "socks",
      "tag": "socks-in",
      "listen": "::",
      "listen_port": 1080
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

This creates a simple SOCKS5 proxy on port 1080 that forwards all traffic directly.

Part 3: Server Configurations

VLESS + Reality Server

The most censorship-resistant TCP-based protocol:

{
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "vless",
      "tag": "vless-reality",
      "listen": "::",
      "listen_port": 443,
      "users": [
        {
          "uuid": "YOUR-UUID-HERE",
          "flow": "xtls-rprx-vision"
        }
      ],
      "tls": {
        "enabled": true,
        "server_name": "www.yahoo.com",
        "reality": {
          "enabled": true,
          "handshake": {
            "server": "www.yahoo.com",
            "server_port": 443
          },
          "private_key": "YOUR-PRIVATE-KEY",
          "short_id": ["abcd1234"]
        }
      }
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

Generate keys:

sing-box generate reality-keypair
# Output:
# PrivateKey: xxxxx (use in server config)
# PublicKey: xxxxx (use in client config)

sing-box generate uuid
# Output: your-uuid-here

Hysteria2 Server

Fastest protocol for censored networks:

Get a TLS certificate first (needed for Hysteria2):

sudo apt install certbot -y
sudo certbot certonly --standalone -d your-domain.com
# Certs at: /etc/letsencrypt/live/your-domain.com/

{
  "inbounds": [
    {
      "type": "hysteria2",
      "tag": "hy2-in",
      "listen": "::",
      "listen_port": 443,
      "users": [
        {
          "password": "your-strong-password"
        }
      ],
      "tls": {
        "enabled": true,
        "certificate_path": "/etc/letsencrypt/live/your-domain.com/fullchain.pem",
        "key_path": "/etc/letsencrypt/live/your-domain.com/privkey.pem"
      }
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

Shadowsocks Server

Classic encrypted proxy:

{
  "inbounds": [
    {
      "type": "shadowsocks",
      "tag": "ss-in",
      "listen": "::",
      "listen_port": 8388,
      "method": "2022-blake3-aes-128-gcm",
      "password": "BASE64-KEY-HERE"
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

Generate Shadowsocks 2022 key:

sing-box generate rand --base64 16    # For aes-128
sing-box generate rand --base64 32    # For aes-256

Multi-Protocol Server (All in One)

Run VLESS+Reality, Hysteria2, and Shadowsocks on the same server:

{
  "log": { "level": "info" },
  "inbounds": [
    {
      "type": "vless",
      "tag": "vless-reality",
      "listen": "::",
      "listen_port": 443,
      "users": [{ "uuid": "YOUR-UUID", "flow": "xtls-rprx-vision" }],
      "tls": {
        "enabled": true,
        "server_name": "www.yahoo.com",
        "reality": {
          "enabled": true,
          "handshake": { "server": "www.yahoo.com", "server_port": 443 },
          "private_key": "YOUR-PRIVATE-KEY",
          "short_id": ["abcd1234"]
        }
      }
    },
    {
      "type": "hysteria2",
      "tag": "hy2-in",
      "listen": "::",
      "listen_port": 8443,
      "users": [{ "password": "your-hy2-password" }],
      "tls": {
        "enabled": true,
        "certificate_path": "/etc/letsencrypt/live/your-domain.com/fullchain.pem",
        "key_path": "/etc/letsencrypt/live/your-domain.com/privkey.pem"
      }
    },
    {
      "type": "shadowsocks",
      "tag": "ss-in",
      "listen": "::",
      "listen_port": 8388,
      "method": "2022-blake3-aes-128-gcm",
      "password": "YOUR-SS-KEY"
    }
  ],
  "outbounds": [
    { "type": "direct", "tag": "direct" },
    { "type": "block", "tag": "block" },
    { "type": "dns", "tag": "dns-out" }
  ],
  "route": {
    "rules": [
      { "protocol": "dns", "outbound": "dns-out" },
      { "ip_is_private": true, "outbound": "direct" }
    ]
  },
  "dns": {
    "servers": [
      { "tag": "google", "address": "https://dns.google/dns-query" }
    ]
  }
}

One server, three protocols, three ports. Users choose which to connect with.

Part 4: DNS Configuration

sing-box has the most advanced DNS handling of any proxy platform.

Basic DNS

{
  "dns": {
    "servers": [
      {
        "tag": "cloudflare",
        "address": "https://1.1.1.1/dns-query",
        "detour": "direct"
      }
    ]
  }
}

Split DNS (Domestic + Foreign)

Route local DNS queries to local servers, foreign queries through the proxy:

{
  "dns": {
    "servers": [
      {
        "tag": "remote",
        "address": "https://1.1.1.1/dns-query",
        "detour": "proxy-out"
      },
      {
        "tag": "local",
        "address": "https://dns.google/dns-query",
        "detour": "direct"
      }
    ],
    "rules": [
      {
        "rule_set": ["geosite-ir"],
        "server": "local"
      }
    ]
  }
}

FakeIP (Advanced)

FakeIP assigns fake IP addresses to domains, avoiding DNS leaks entirely:

{
  "dns": {
    "servers": [
      {
        "tag": "remote",
        "address": "https://1.1.1.1/dns-query"
      },
      {
        "tag": "fakeip",
        "address": "fakeip"
      }
    ],
    "fakeip": {
      "enabled": true,
      "inet4_range": "198.18.0.0/15"
    },
    "rules": [
      {
        "query_type": ["A", "AAAA"],
        "server": "fakeip"
      }
    ]
  }
}

FakeIP means DNS queries never leave your device — the proxy resolves them on the server side. Zero DNS leaks.

Part 5: Routing Rules

Block Ads

{
  "route": {
    "rule_set": [
      {
        "tag": "geosite-ads",
        "type": "remote",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-category-ads-all.srs"
      }
    ],
    "rules": [
      {
        "rule_set": ["geosite-ads"],
        "outbound": "block"
      }
    ]
  }
}

Bypass Local Traffic (Iran)

{
  "route": {
    "rule_set": [
      {
        "tag": "geoip-ir",
        "type": "remote",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-ir.srs"
      },
      {
        "tag": "geosite-ir",
        "type": "remote",
        "format": "binary",
        "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-ir.srs"
      }
    ],
    "rules": [
      {
        "rule_set": ["geoip-ir", "geosite-ir"],
        "outbound": "direct"
      },
      {
        "geoip": ["private"],
        "outbound": "direct"
      }
    ],
    "final": "proxy-out"
  }
}

Route Specific Apps (Process-Based)

{
  "route": {
    "rules": [
      {
        "process_name": ["telegram.exe", "org.telegram.messenger"],
        "outbound": "proxy-out"
      },
      {
        "process_name": ["chrome.exe", "firefox.exe"],
        "outbound": "proxy-out"
      }
    ],
    "final": "direct"
  }
}

Part 6: Client Configuration

sing-box as Client

{
  "log": { "level": "info" },
  "dns": {
    "servers": [
      { "tag": "remote", "address": "https://1.1.1.1/dns-query", "detour": "proxy" },
      { "tag": "local", "address": "local" }
    ]
  },
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "address": ["172.19.0.1/30"],
      "auto_route": true,
      "strict_route": true,
      "sniff": true
    }
  ],
  "outbounds": [
    {
      "type": "vless",
      "tag": "proxy",
      "server": "your-server.com",
      "server_port": 443,
      "uuid": "your-uuid",
      "flow": "xtls-rprx-vision",
      "tls": {
        "enabled": true,
        "server_name": "www.yahoo.com",
        "utls": { "enabled": true, "fingerprint": "chrome" },
        "reality": {
          "enabled": true,
          "public_key": "YOUR-PUBLIC-KEY",
          "short_id": "abcd1234"
        }
      }
    },
    { "type": "direct", "tag": "direct" },
    { "type": "block", "tag": "block" }
  ],
  "route": {
    "rules": [
      { "ip_is_private": true, "outbound": "direct" },
      { "protocol": "dns", "outbound": "dns-out" }
    ],
    "final": "proxy",
    "auto_detect_interface": true
  }
}

The tun inbound creates a virtual network interface

Key TUN settings explained:

• auto_route: true -- automatically adds routes so all system traffic goes through the tunnel
• strict_route: true -- prevents traffic from leaking around the tunnel (recommended)
• sniff: true -- inspects traffic to determine the destination domain (needed for rule-based routing)
• If you don't want system-wide proxy, use a socks or http inbound instead of tun (then configure apps individually)

that captures all system traffic — like a VPN.

Apps That Use sing-box

You don't need to run sing-box directly. These apps use sing-box as their core engine:

• Hiddify — easiest GUI, auto-generates sing-box configs
• Nekobox — Android, power-user features
• sing-box for Android — official app (basic)

When you import a proxy link into these apps, they generate the sing-box JSON automatically.

Part 7: sing-box vs Xray vs Hysteria2

Choose sing-box when: You want one tool for everything, need Hysteria2 + VLESS on one server, or want advanced routing/DNS.

Choose Xray + 3X-UI when: You need a web panel to manage users, which is easier for most people.

Choose standalone Hysteria2 when: You only need Hysteria2 and nothing else.

Part 8: Security Hardening

Block Abuse on Server

Add to your server config's route rules:

{
  "route": {
    "rules": [
      {
        "port": [25, 465, 587],
        "outbound": "block"
      },
      {
        "rule_set": ["geosite-ads"],
        "outbound": "block"
      }
    ]
  }
}

This blocks SMTP (spam) and ads at the proxy level.

Use Fortify

Route Through WARP (Clean IP)

sing-box natively supports WireGuard, so you can add WARP as an outbound:

{
  "type": "wireguard",
  "tag": "warp-out",
  "private_key": "YOUR-WARP-PRIVATE-KEY",
  "peer_public_key": "bmXOC+F1FxEMF9dyiK2H5/1SUtzH0JuVo51h2wPfgyo=",
  "server": "162.159.192.1",
  "server_port": 2408,
  "reserved": [0, 0, 0]
}

Generate the private key and reserved bytes using wgcf (see WARP Setup). Then route specific domains through it in your route rules.

Fortify auto-detects sing-box and hardens your server:

bash <(curl -sL https://github.com/SamNet-dev/fortify/raw/main/install.sh)
fortify

Firewall

# Open only the ports you configured
sudo ufw allow 443/tcp       # VLESS+Reality
sudo ufw allow 8443/udp      # Hysteria2
sudo ufw allow 8388/tcp      # Shadowsocks

Troubleshooting

Version Compatibility

sing-box config format changes between versions. Always check your version:

sing-box version

If you copy a config from a blog or tutorial, make sure it matches your installed version. Configs from older versions may show warnings or fail on newer sing-box.

# Validate config
sing-box check -c /etc/sing-box/config.json

# View logs
sudo journalctl -u sing-box -f

# Test a specific outbound
sing-box tools fetch --outbound proxy "https://ifconfig.me"

Related Guides

• Proxy Client Setup — client apps that use sing-box
• Hysteria2 Setup — standalone Hysteria2 guide
• 3X-UI Panel Setup — Xray with web panel (alternative to sing-box)
• Xray Routing Guide — Xray routing rules
• Complete Proxy Guide — every protocol explained
• Cloudflare WARP Setup — WARP as outbound
• Clean Cloudflare IPs — CDN bypass
• Every Way to Bypass Censorship — all methods compared
• Fortify Server Hardening — secure your server
• paqctl Setup — alternative bypass (violated TCP)

SamNet Open Source Tools

Related Tools

• VPN Leak Test — verify proxy works
• Port Scanner — check ports
• What's My IP — verify IP changed
• Speed Test — test proxy speed