How to Set Up a Sing-Box Server

This guide deploys a Sing-Box server using VLESS + Reality + XTLS Vision, with optional Warp routing and Fail2Ban hardening.

It is designed for Debian or Ubuntu VPS environments and follows the client guide for consistency.

1. System Requirements

• Debian or Ubuntu VPS
• Root or sudo access
• TCP port 443 open (recommended)
• Access to configure the firewall (UFW recommended)

2. Docker and Compose Installation

We use Docker to ensure reproducible deployment.

2.1 Docker and Compose Installation

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose

Enable Docker:

sudo systemctl enable --now docker

Verify:

docker --version
docker-compose --version

3. Project Directory

mkdir -p ~/software/sing-box/config
cd ~/software/sing-box

4. Docker Compose Configuration

Create a docker-compose.yml file:

services:
  sing-box:
    image: ghcr.io/sagernet/sing-box
    container_name: sing-box
    restart: always
    network_mode: host
    volumes:
      - ./config:/etc/sing-box
    command: run -C /etc/sing-box

Start the service:

docker-compose up -d

Check the container status:

docker ps | grep sing-box

5. Shared Credentials

Generate the credentials once per deployment and share the required values with the client.

• UUID → shared between server and client

• Reality keypair → generated on server

  • private_key → server only
  • public_key → client only

5.1 UUID Generation

uuidgen

Example:

123e4567-e89b-12d3-a456-426614174000

5.2 Reality Key Pair Generation

sing-box generate reality-keypair

Output:

PrivateKey: xxxx   (SERVER ONLY)
PublicKey:  xxxx    (CLIENT USE)

6. Sing-Box Server Configuration

Create the configuration file:

mkdir -p config
nano config/config.json

6.1 VLESS and Reality Inbound

{
  "log": {
    "level": "warning",
    "timestamp": true
  },

  "inbounds": [
    {
      "type": "vless",
      "tag": "vless-in",
      "listen": "0.0.0.0",
      "listen_port": 443,

      "users": [
        {
          "uuid": "YOUR_UUID",
          "flow": "xtls-rprx-vision"
        }
      ],

      "tls": {
        "enabled": true,
        "server_name": "www.cloudflare.com",

        "reality": {
          "enabled": true,
          "handshake": {
            "server": "www.cloudflare.com",
            "server_port": 443
          },

          "private_key": "YOUR_PRIVATE_KEY",
          "short_id": "8f3a7b2c9d"
        }
      }
    }
  ],

  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

6.2 Configuration Notes

• The UUID must match the client
• The private key must match the Reality key
• The public key is used only on the client
• short_id must match on both sides
• server_name must match the client configuration

7. Service Management

7.1 Service Startup

docker-compose up -d

7.2 Service Restart

docker-compose restart

7.3 Service Shutdown

docker-compose down

7.4 Service Logs

docker logs sing-box

8. Warp Routing

This optional section uses WireGuard for outbound routing.

8.1 WireGuard Installation

sudo apt install -y wireguard-tools

8.2 Warp Configuration

bash <(curl -fsSL git.io/warp.sh) wg4

Edit the WireGuard configuration:

nano /etc/wireguard/wgcf.conf

8.3 Warp Startup

sudo wg-quick up wgcf
sudo systemctl enable wg-quick@wgcf
sudo wg

9. Fail2Ban Setup

9.1 Fail2Ban Installation

sudo apt install -y fail2ban

9.2 Fail2Ban Activation

sudo systemctl enable fail2ban
sudo systemctl start fail2ban

10. Firewall Setup (Recommended)

ufw allow 443/tcp
ufw enable
ufw status

11. Backup and Restore

11.1 Configuration Backup

mkdir -p ~/backup/sing-box
cp -r config ~/backup/sing-box/

11.2 Configuration Restore

rm -rf config
cp -r ~/backup/sing-box/config ./
docker-compose restart

12. Troubleshooting

12.1 Service Logs

docker logs sing-box

12.2 Warp Diagnostics

wg
ip route

12.3 Common Issues

• Port 443 in use
• UUID mismatch
• Reality key mismatch
• short_id mismatch

13. Quick Checklist

• Docker running
• Sing-Box container started
• UUID correct (shared)
• Reality keys matched
• short_id identical
• Port 443 open
• Warp working (optional)
• Fail2Ban enabled