# sing-box Configuration Overview

## Version Info
- **Stable**: v1.13.3 (March 2026)
- **Alpha**: v1.14.0-alpha.6
- **Repository**: github.com/SagerNet/sing-box (31.8k stars)
- **Docs**: https://sing-box.sagernet.org

## Top-Level Config Structure

```json
{
  "$schema": "",
  "log": {
    "disabled": false,
    "level": "info",
    "output": "",
    "timestamp": true
  },
  "dns": {},
  "ntp": {
    "enabled": false,
    "server": "time.apple.com",
    "server_port": 123,
    "interval": "30m"
  },
  "certificate": {},
  "certificate_providers": [],
  "endpoints": [],
  "inbounds": [],
  "outbounds": [],
  "route": {},
  "services": [],
  "experimental": {}
}
```

## All Inbound Protocol Types (17)

| Type | Description | Platform |
|------|-------------|----------|
| `direct` | Direct/injectable forwarding | All |
| `mixed` | SOCKS + HTTP combined proxy | All |
| `socks` | SOCKS4/4a/5 proxy server | All |
| `http` | HTTP/HTTPS proxy server | All |
| `shadowsocks` | Shadowsocks server (incl. 2022 ciphers) | All |
| `vmess` | VMess protocol server | All |
| `vless` | VLESS server (XTLS-Vision flow) | All |
| `trojan` | Trojan server with fallback | All |
| `naive` | NaiveProxy server | All |
| `hysteria` | Hysteria QUIC-based server | All |
| `hysteria2` | Hysteria2 with masquerade | All |
| `shadowtls` | ShadowTLS server | All |
| `tuic` | TUIC QUIC-based server | All |
| `anytls` | AnyTLS server (v1.12.0+) | All |
| `tun` | TUN virtual interface | All |
| `redirect` | TCP redirect transparent proxy | Linux |
| `tproxy` | Full transparent proxy (TCP+UDP) | Linux |

## All Outbound Protocol Types (20)

| Type | Description |
|------|-------------|
| `direct` | Direct connection |
| `block` | Block/reject traffic |
| `socks` | SOCKS proxy client |
| `http` | HTTP proxy client |
| `shadowsocks` | Shadowsocks client |
| `vmess` | VMess client |
| `vless` | VLESS client (XTLS-Vision) |
| `trojan` | Trojan client |
| `naive` | NaiveProxy client |
| `wireguard` | WireGuard (deprecated → endpoint) |
| `hysteria` | Hysteria client |
| `hysteria2` | Hysteria2 client (port hopping) |
| `shadowtls` | ShadowTLS client |
| `tuic` | TUIC client |
| `anytls` | AnyTLS client (v1.12.0+) |
| `tor` | Tor network client |
| `ssh` | SSH tunnel client |
| `dns` | DNS outbound (removed in 1.13.0) |
| `selector` | Manual proxy selection group |
| `urltest` | Auto latency-based selection group |

## Endpoint Types

| Type | Description | Since |
|------|-------------|-------|
| `wireguard` | WireGuard VPN endpoint (replaces outbound) | v1.11.0 |
| `tailscale` | Tailscale integration | v1.11.0 |

## Experimental Section

```json
{
  "experimental": {
    "cache_file": {
      "enabled": true,
      "path": "cache.db",
      "cache_id": "",
      "store_fakeip": false,
      "store_rdrc": false,
      "rdrc_timeout": "7d"
    },
    "clash_api": {
      "external_controller": "127.0.0.1:9090",
      "external_ui": "",
      "external_ui_download_url": "",
      "external_ui_download_detour": "",
      "secret": "",
      "default_mode": ""
    },
    "v2ray_api": {
      "listen": "127.0.0.1:8080",
      "stats": {
        "enabled": true,
        "inbounds": ["in-tag"],
        "outbounds": ["out-tag"],
        "users": ["user"]
      }
    }
  }
}
```

## Services (v1.13.0+)

Background services configured in the `services` array:
- **resolved** — Built-in DNS resolver service
- **ccm** — Client Configuration Manager
- **ocm** — Outbound Configuration Manager
- **ssmapi** — SSM API service
- **derp** — DERP relay service
- **oom_killer** — OOM killer service

## CLI Commands

```bash
sing-box run -c config.json          # Run with config
sing-box run -C /etc/sing-box/       # Run with config directory (merges all .json)
sing-box check -c config.json        # Validate config
sing-box format -c config.json -w    # Format config (pretty-print, -w writes back)
sing-box merge output.json -C dir/   # Merge multiple configs into one
sing-box version                     # Show version
sing-box generate tls-keypair        # Generate TLS key pair
sing-box generate reality-keypair    # Generate Reality key pair
sing-box generate rand --base64 32   # Generate random bytes
```

## Key Deprecations Timeline

| Version | Deprecated | Replacement |
|---------|-----------|-------------|
| v1.8.0 | `geoip`, `geosite` databases | `rule_set` (local/remote) |
| v1.11.0 | Inbound `sniff`, `domain_strategy` | Route rule actions |
| v1.11.0 | WireGuard outbound | WireGuard endpoint |
| v1.11.0 | Separate `inet4_address`/`inet6_address` | Unified `address` |
| v1.13.0 | `dns` outbound type | `hijack-dns` rule action |
| v1.14.0 | ACME in TLS inbound | `certificate_providers` |

## Shadowsocks Cipher Methods

**Modern (recommended):**
- `2022-blake3-aes-128-gcm`
- `2022-blake3-aes-256-gcm`
- `2022-blake3-chacha20-poly1305`

**Legacy:**
- `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`
- `chacha20-ietf-poly1305`, `xchacha20-ietf-poly1305`
- `none` (no encryption)