singboxer/references/ref-protocols.md

# sing-box Protocol Reference

## Shadowsocks

### Client
```json
{
  "type": "shadowsocks",
  "tag": "ss-out",
  "server": "server.example.com",
  "server_port": 8388,
  "method": "2022-blake3-aes-256-gcm",
  "password": "base64-encoded-key",
  "plugin": "",
  "plugin_opts": "",
  "network": "tcp",
  "udp_over_tcp": false,
  "multiplex": {}
}
```

### Server
```json
{
  "type": "shadowsocks",
  "tag": "ss-in",
  "listen": "::",
  "listen_port": 8388,
  "method": "2022-blake3-aes-256-gcm",
  "password": "base64-encoded-key",
  "users": [
    {
      "name": "user1",
      "password": "user-key"
    }
  ]
}
```

Key generation:
```bash
# For 2022-blake3-aes-256-gcm (32 bytes)
sing-box generate rand --base64 32
# For 2022-blake3-aes-128-gcm (16 bytes)
sing-box generate rand --base64 16
```

## VMess

### Client
```json
{
  "type": "vmess",
  "tag": "vmess-out",
  "server": "server.example.com",
  "server_port": 443,
  "uuid": "uuid-here",
  "security": "auto",
  "alter_id": 0,
  "global_padding": true,
  "authenticated_length": true,
  "tls": {},
  "transport": {},
  "multiplex": {}
}
```

### Server
```json
{
  "type": "vmess",
  "tag": "vmess-in",
  "listen": "::",
  "listen_port": 443,
  "users": [
    {
      "name": "user1",
      "uuid": "uuid-here",
      "alterId": 0
    }
  ],
  "tls": {},
  "transport": {}
}
```

## VLESS

### Client
```json
{
  "type": "vless",
  "tag": "vless-out",
  "server": "server.example.com",
  "server_port": 443,
  "uuid": "uuid-here",
  "flow": "xtls-rprx-vision",
  "tls": {
    "enabled": true,
    "server_name": "example.com",
    "utls": {
      "enabled": true,
      "fingerprint": "chrome"
    }
  },
  "transport": {},
  "multiplex": {}
}
```

### Server
```json
{
  "type": "vless",
  "tag": "vless-in",
  "listen": "::",
  "listen_port": 443,
  "users": [
    {
      "name": "user1",
      "uuid": "uuid-here",
      "flow": "xtls-rprx-vision"
    }
  ],
  "tls": {},
  "transport": {}
}
```

## Trojan

### Client
```json
{
  "type": "trojan",
  "tag": "trojan-out",
  "server": "server.example.com",
  "server_port": 443,
  "password": "password",
  "tls": {
    "enabled": true,
    "server_name": "example.com"
  },
  "transport": {},
  "multiplex": {}
}
```

### Server
```json
{
  "type": "trojan",
  "tag": "trojan-in",
  "listen": "::",
  "listen_port": 443,
  "users": [
    {
      "name": "user1",
      "password": "password"
    }
  ],
  "tls": {},
  "fallback": {
    "server": "127.0.0.1",
    "server_port": 8080
  },
  "fallback_for_alpn": {
    "h2": {
      "server": "127.0.0.1",
      "server_port": 8081
    }
  }
}
```

## Hysteria2

### Client
```json
{
  "type": "hysteria2",
  "tag": "hy2-out",
  "server": "server.example.com",
  "server_port": 443,
  "up_mbps": 100,
  "down_mbps": 200,
  "password": "password",
  "obfs": {
    "type": "salamander",
    "password": "obfs-password"
  },
  "tls": {
    "enabled": true,
    "server_name": "example.com"
  }
}
```

### Server
```json
{
  "type": "hysteria2",
  "tag": "hy2-in",
  "listen": "::",
  "listen_port": 443,
  "up_mbps": 0,
  "down_mbps": 0,
  "users": [
    {
      "name": "user1",
      "password": "password"
    }
  ],
  "obfs": {
    "type": "salamander",
    "password": "obfs-password"
  },
  "masquerade": "https://example.com",
  "tls": {}
}
```

## TUIC

### Client
```json
{
  "type": "tuic",
  "tag": "tuic-out",
  "server": "server.example.com",
  "server_port": 443,
  "uuid": "uuid-here",
  "password": "password",
  "congestion_control": "bbr",
  "udp_relay_mode": "quic",
  "zero_rtt_handshake": false,
  "heartbeat": "10s",
  "tls": {
    "enabled": true,
    "server_name": "example.com"
  }
}
```
Congestion control: `cubic` (default), `new_reno`, `bbr`
UDP relay: `native` (default), `quic`

## ShadowTLS

### Client (chained with another outbound)
```json
{
  "type": "shadowtls",
  "tag": "shadowtls-out",
  "server": "server.example.com",
  "server_port": 443,
  "version": 3,
  "password": "password",
  "tls": {
    "enabled": true,
    "server_name": "www.microsoft.com"
  }
}
```

### Chaining ShadowTLS + Shadowsocks
```json
{
  "outbounds": [
    {
      "type": "shadowsocks",
      "tag": "ss-out",
      "detour": "shadowtls-out",
      "method": "2022-blake3-aes-256-gcm",
      "password": "ss-key"
    },
    {
      "type": "shadowtls",
      "tag": "shadowtls-out",
      "server": "server.example.com",
      "server_port": 443,
      "version": 3,
      "password": "stls-password",
      "tls": {
        "enabled": true,
        "server_name": "www.microsoft.com"
      }
    }
  ]
}
```

## AnyTLS (v1.12.0+)

### Client
```json
{
  "type": "anytls",
  "tag": "anytls-out",
  "server": "server.example.com",
  "server_port": 443,
  "password": "password",
  "idle_timeout": "15m",
  "min_idle_session": 2,
  "padding_scheme": "",
  "tls": {
    "enabled": true,
    "server_name": "example.com"
  }
}
```

## WireGuard (Endpoint)

```json
{
  "endpoints": [
    {
      "type": "wireguard",
      "tag": "wg-ep",
      "system": false,
      "name": "wg0",
      "mtu": 1420,
      "address": [
        "10.0.0.2/32",
        "fd00::2/128"
      ],
      "private_key": "private-key-base64",
      "listen_port": 51820,
      "peers": [
        {
          "address": "server.example.com",
          "port": 51820,
          "public_key": "peer-public-key-base64",
          "pre_shared_key": "",
          "allowed_ips": ["0.0.0.0/0", "::/0"],
          "persistent_keepalive_interval": "25s",
          "reserved": [0, 0, 0]
        }
      ]
    }
  ]
}
```

## SSH Tunnel

```json
{
  "type": "ssh",
  "tag": "ssh-out",
  "server": "server.example.com",
  "server_port": 22,
  "user": "username",
  "password": "password",
  "private_key": "",
  "private_key_path": "~/.ssh/id_ed25519",
  "private_key_passphrase": "",
  "host_key_algorithms": [],
  "client_version": "SSH-2.0-OpenSSH_8.9"
}
```

## Selector (Manual Proxy Group)

```json
{
  "type": "selector",
  "tag": "proxy",
  "outbounds": ["hy2-hk", "vless-jp", "ss-us", "direct"],
  "default": "hy2-hk",
  "interrupt_exist_connections": true
}
```

## URLTest (Auto Proxy Group)

```json
{
  "type": "urltest",
  "tag": "auto",
  "outbounds": ["hy2-hk", "vless-jp", "ss-us"],
  "url": "https://www.gstatic.com/generate_204",
  "interval": "3m",
  "tolerance": 50,
  "idle_timeout": "30m",
  "interrupt_exist_connections": true
}
```

## Multiplex (Mux) — Shared Options

```json
{
  "multiplex": {
    "enabled": true,
    "protocol": "h2mux",
    "max_connections": 4,
    "min_streams": 4,
    "max_streams": 0,
    "padding": true,
    "brutal": {
      "enabled": true,
      "up_mbps": 100,
      "down_mbps": 200
    }
  }
}
```
Protocols: `smux`, `yamux`, `h2mux` (default, recommended)