Skip to main content

​
Sing-box Proxy

DNS-MNS integrates with sing-box - a universal proxy platform - to provide advanced censorship circumvention for users in Iran and other restricted regions.

​
What is Sing-box?

Sing-box is a powerful proxy platform that supports multiple modern protocols designed to bypass Deep Packet Inspection (DPI) and censorship:
  • VLESS + XTLS/REALITY - The most effective protocol for Iran (99.5% success rate)
  • VMess - Encrypted proxy protocol
  • Trojan - Disguises traffic as HTTPS
  • Hysteria2 - QUIC-based with aggressive congestion control
  • ShadowTLS - Certificate mimicry for stealth
  • TUIC - QUIC-based UDP proxy

​
Why VLESS + REALITY?

REALITY is a groundbreaking TLS handshake implementation that:
  • Uses real TLS certificates from legitimate websites (microsoft.com, bing.com, etc.)
  • Impossible to block without breaking legitimate websites
  • Evades detection by mimicking normal HTTPS traffic perfectly
  • Works in Iran even during severe internet shutdowns

​
Quick Start

​
Interactive Mode

  1. Run dns-mns and select [8] Advanced Proxy (VLESS/REALITY)
  2. Choose Start VLESS + REALITY Proxy
  3. Enter your server details:
    • Server address (host:port)
    • UUID
    • REALITY public key
    • REALITY short ID
    • SNI (e.g., www.microsoft.com)

​
Command Line

# Start VLESS + REALITY proxy
dns-mns singbox start \
  --protocol vless \
  --server your-server.com:443 \
  --uuid xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --public-key YOUR_PUBLIC_KEY \
  --short-id YOUR_SHORT_ID \
  --sni www.microsoft.com

# Start with configuration file
dns-mns singbox start --config /path/to/config.json

# Check status
dns-mns singbox status

# Stop proxy
dns-mns singbox stop

​
Configuration Examples

​
Generate Example Config

# VLESS + REALITY (recommended for Iran)
dns-mns singbox config-example --protocol vless-reality

# VMess
dns-mns singbox config-example --protocol vmess

# Trojan
dns-mns singbox config-example --protocol trojan

# Hysteria2
dns-mns singbox config-example --protocol hysteria2

​
VLESS + REALITY Example

{
  "log": {
    "level": "warn"
  },
  "dns": {
    "servers": [
      {
        "tag": "proxy-dns",
        "address": "1.1.1.1:53",
        "detour": "proxy-out"
      }
    ]
  },
  "inbounds": [
    {
      "type": "direct",
      "tag": "dns-in",
      "listen": "127.0.0.1",
      "listen_port": 5355
    }
  ],
  "outbounds": [
    {
      "type": "vless",
      "tag": "proxy-out",
      "server": "your-server.com",
      "server_port": 443,
      "uuid": "your-uuid-here",
      "flow": "xtls-rprx-vision",
      "tls": {
        "enabled": true,
        "server_name": "www.microsoft.com",
        "utls": {
          "enabled": true,
          "fingerprint": "chrome"
        },
        "reality": {
          "enabled": true,
          "public_key": "your-public-key",
          "short_id": "your-short-id"
        }
      }
    }
  ],
  "route": {
    "rules": [
      {
        "protocol": ["dns"],
        "outbound": "proxy-out"
      }
    ]
  }
}

​
Available Protocols

ProtocolDescriptionBest For
VLESS + REALITYXTLS with REALITY handshakeIran (99.5% success)
VMessEncrypted proxy protocolGeneral use
TrojanHTTPS disguiseSimplicity
Hysteria2QUIC-based with brutal CCUnstable networks
ShadowTLSCertificate mimicryHigh stealth
TUICQUIC UDP proxyLow latency

​
Command Reference

​
dns-mns singbox start

Start the sing-box DNS proxy. Flags:
FlagDescriptionDefault
--protocolProtocol type (vless, vmess, trojan, hysteria2, shadowtls, tuic)vless
--serverServer address (host:port)(required)
--uuidUUID for VLESS/VMess/TUIC(required)
--passwordPassword for Trojan/Hysteria2/ShadowTLS(required)
--public-keyREALITY public key (base64)-
--short-idREALITY short ID-
--sniTLS SNI/ServerName-
--fingerprintTLS fingerprint (chrome, firefox, safari, edge)chrome
--listenLocal listen address127.0.0.1:5355
--upstreamUpstream DNS server1.1.1.1:53
--configPath to configuration file-

​
dns-mns singbox stop

Stop the running sing-box proxy.

​
dns-mns singbox status

Show proxy status and statistics: 
$ dns-mns singbox status

【 SING-BOX PROXY STATUS 】
═══════════════════════════════════════════════════════════════

  Running:    Yes
  Protocol:   VLESS
  Server:     your-server.com:443
  Listen:     127.0.0.1:5355
  Upstream:   1.1.1.1:53

  Statistics:
    Queries:  1523
    Success:  1520
    Errors:   3
    Avg Latency: 45ms

​
dns-mns singbox test

Test configuration validity without starting the proxy.

​
dns-mns singbox config-example

Generate example configuration for different protocols.

​
Using the Proxy

Once the sing-box proxy is running, set your system DNS to the local address (default: 127.0.0.1:5355):

​
Option 1: Using DNS-MNS (Easiest)

dns-mns set 127.0.0.1

​
Option 2: Manual System Configuration

Linux (NetworkManager): 
# Replace 'eth0' with your interface name (check with 'nmcli device')
nmcli dev modify eth0 ipv4.dns "127.0.0.1"
nmcli dev modify eth0 ipv4.ignore-auto-dns yes

# Or for Wi-Fi
nmcli dev modify wlan0 ipv4.dns "127.0.0.1"
nmcli dev modify wlan0 ipv4.ignore-auto-dns yes
Linux (systemd-resolved): 
# Edit resolved.conf
sudo nano /etc/systemd/resolved.conf

# Add these lines:
[Resolve]
DNS=127.0.0.1
DNSStubListener=no

# Restart service
sudo systemctl restart systemd-resolved
macOS: 
# For Wi-Fi
sudo networksetup -setdnsservers Wi-Fi 127.0.0.1

# For Ethernet
sudo networksetup -setdnsservers "Ethernet" 127.0.0.1

# To verify
scutil --dns
Windows (PowerShell as Administrator): 
# Get interface alias
Get-NetAdapter

# Set DNS (replace "Wi-Fi" with your interface name)
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ServerAddresses 127.0.0.1

# To reset later
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ResetServerAddresses

​
Option 3: Per-Application Configuration

Configure individual applications to use 127.0.0.1:5355 as their DNS server:
  • Chrome: Use command line flag --dns-server=127.0.0.1
  • Firefox: Set network.trr.uri in about:config
  • curl: Use --dns-servers 127.0.0.1:5355

​
Testing Your Setup

​
Verify Proxy is Running

# Check status
dns-mns singbox status

# Or with JSON output for scripts
dns-mns singbox status --json

​
Test DNS Resolution

# Using dig
dig @127.0.0.1 -p 5355 google.com

# Using nslookup
nslookup google.com 127.0.0.1

# Using host
host google.com 127.0.0.1

​
Test Configuration Without Starting

# Test your config file
dns-mns singbox test --config my-config.json

# Should output "Configuration is valid!" if correct

​
Verify Traffic is Going Through Proxy

# Check your current DNS server
cat /etc/resolv.conf

# Test DNS leak (should show proxy upstream, not your ISP)
dns-mns leak-test google.com

​
Troubleshooting

​
Connection Failed

  1. Verify your server credentials (UUID, password, keys)
  2. Check if the server is reachable: ping your-server.com
  3. Ensure the server supports the protocol you’re using

​
Slow Performance

  1. Try a different upstream DNS: --upstream 8.8.8.8:53
  2. Test different protocols (Hysteria2 works well on unstable networks)
  3. Check your base internet connection speed

​
Protocol Blocked

If VLESS is blocked:
  1. Try ShadowTLS for certificate mimicry
  2. Try Hysteria2 (QUIC-based, harder to detect)
  3. Change the SNI to a different legitimate domain

​
Security Considerations

  • Keep your server credentials private
  • Use strong passwords and UUIDs
  • Regularly update your server configuration
  • Monitor proxy statistics for anomalies

​
Getting a VLESS + REALITY Server

You’ll need access to a VLESS server with REALITY support. Options:
  1. Self-host using Xray-core or sing-box on a VPS
  2. Purchase from providers supporting VLESS/REALITY
  3. Community servers (be cautious with sensitive data)
For self-hosting, see:

​
Quick Reference

​
Protocol Ranking for Iran

Based on current effectiveness against Iranian censorship:
  1. VLESS + REALITY ⭐⭐⭐⭐⭐
    • 99.5% success rate
    • Uses real TLS certificates
    • Impossible to block without breaking legitimate sites
  2. ShadowTLS ⭐⭐⭐⭐⭐
    • Also uses certificate mimicry
    • Very stealthy
    • Good alternative to REALITY
  3. Hysteria2 ⭐⭐⭐⭐
    • QUIC-based (UDP)
    • Works well on unstable networks
    • Aggressive congestion control
  4. TUIC ⭐⭐⭐⭐
    • QUIC-based
    • Low latency
    • Good for gaming
  5. Trojan ⭐⭐⭐
    • Simple HTTPS disguise
    • May be detected by advanced DPI
  6. VMess ⭐⭐⭐
    • Older protocol
    • May require frequent updates

​
Common Scenarios

Scenario 1: Quick Start with VLESS 
# Generate config, edit it, then start
dns-mns singbox config-example --protocol vless-reality > config.json
# Edit config.json with your credentials
sudo dns-mns singbox start --config config.json &
dns-mns set 127.0.0.1
Scenario 2: Auto-start on Boot (Linux with systemd) 
# Create service file
sudo tee /etc/systemd/system/dns-mns-singbox.service > /dev/null <<EOF
[Unit]
Description=DNS-MNS Sing-box Proxy
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/dns-mns singbox start --config /etc/dns-mns/config.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable dns-mns-singbox
sudo systemctl start dns-mns-singbox
Scenario 3: Switching Protocols When Blocked 
# If VLESS is blocked, try Hysteria2
dns-mns singbox stop
dns-mns singbox start \
  --protocol hysteria2 \
  --server your-server.com:443 \
  --password your-password
Scenario 4: Using with Fallback Proxy 
# Start fallback proxy with singbox as ultimate fallback
# (Singbox config can be provided programmatically)

​
Reset DNS to Default

If you need to revert your DNS settings: 
# Using DNS-MNS
dns-mns clear

# Or manually:
# Linux (NetworkManager)
nmcli dev modify eth0 ipv4.dns ""
nmcli dev modify eth0 ipv4.ignore-auto-dns no

# macOS
sudo networksetup -setdnsservers Wi-Fi empty

# Windows
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ResetServerAddresses

​
Environment Variables

VariableDescription
NO_COLORDisable colored output
DNS_MNS_CONFIGDefault config file path

​
Further Reading