Sing Box Server Configuration and Installation Guide

Install sing-box and prepare the server configuration

This guide uses a Linux server with sudo access, systemd, sing-box 1.14 and a single-user Shadowsocks 2022 setup. You need SSH access and control over the host firewall and cloud security group. To import an existing profile on a phone or computer, use the client guide.

The installation script supports the DEB/RPM distributions and Arch Linux listed by the project. The service commands below require systemd; they do not apply unchanged to OpenWrt, containers or other init systems. Back up an existing installation and allow for downtime before making changes.

Make sure curl is installed, then download and inspect the official script before installing the stable package. Run the commands one at a time; press q to exit less. The official package repository is another option. A server uses the command-line core, not the SFW/SFL graphical application.

curl -fsSL https://sing-box.app/install.sh -o sing-box-install.sh
less sing-box-install.sh
sudo sh sing-box-install.sh
sing-box version

Generate a key for this server. The 2022-blake3-aes-128-gcm method requires 16 random bytes encoded as Base64. Keep the output for the password field below; do not reuse a tutorial key or post your own key in comments.

sing-box generate rand --base64 16

Check the actual service command with systemctl cat sing-box. The official 1.14.2 service loads -C /etc/sing-box; make sure no other JSON files in that directory will be loaded unintentionally. Edit /etc/sing-box/config.json with sudoedit /etc/sing-box/config.json, replace the placeholder with your generated key, and save the complete JSON:

{
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "shadowsocks",
      "tag": "ss-in",
      "listen": "0.0.0.0",
      "listen_port": 8388,
      "network": "tcp",
      "method": "2022-blake3-aes-128-gcm",
      "password": "REPLACE_WITH_YOUR_GENERATED_KEY",
      "multiplex": {
        "enabled": true
      }
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ]
}

This example listens on IPv4 TCP port 8388 with multiplexing enabled; enable multiplex on the client too. Allow that TCP port in the firewall while preserving SSH access, rather than disabling the firewall. Check cloud security groups and any NAT forwarding as well. Restrict source addresses when practical. IPv6 requires a separate check of the listen address and network rules.

Check configuration paths and file access

The configuration contains a secret key: keep it out of public websites and subscription directories. Back up existing files and restrict access while allowing the actual service user to read them. If you changed the service command, adjust the check below to match its ExecStart. A successful check as root does not confirm that the service user has the correct permissions.

Does this example need a TLS certificate?

This Shadowsocks 2022 example does not use a TLS certificate or require a domain name. Handle TLS, certificates and domain names separately if you choose a protocol such as Trojan or Hysteria2. The old inline ACME configuration is deprecated in sing-box 1.14; new setups should consult the ACME certificate provider. Do not add TLS fields from an unrelated tutorial to this example.

Check, start and inspect the service

Check the same working directory and configuration directory used by the service. Fix the first reported error before restarting:

sudo sing-box -D /var/lib/sing-box -C /etc/sing-box check

After the check passes, start or restart the service. A restart interrupts existing connections. Once it is working, use sudo systemctl enable sing-box if you want it to start at boot.

sudo systemctl restart sing-box

Inspect the service status and recent logs. active (running) confirms a running process, not a working client connection. Use sudo systemctl stop sing-box to stop it.

sudo systemctl status sing-box --no-pager
sudo journalctl -u sing-box --output cat -n 50 --no-pager

Connect a client and diagnose failures

Use a complete client configuration that supports Shadowsocks 2022. Its Shadowsocks outbound needs the public IPv4 address of your server, port 8388, method 2022-blake3-aes-128-gcm, the same key, and multiplex.enabled set to true. Do not import the server inbounds JSON as a client profile. Client inbounds, DNS and routing still depend on the device and how it will be used; compare the fields in the official server and client examples.

Save the complete client profile, follow the user guide to start it, and test access to a website. For timeouts, check the address, TCP port, firewall and security group. For authentication failures, check the method and key; also check both system clocks for Shadowsocks 2022. If the service fails to start, use the first log error to distinguish JSON, key format, port conflicts and file permissions. If the connection works but browsing fails, check server internet access and client DNS and routing before reinstalling anything.

Before upgrading, keep a recoverable configuration and record the installed version, then check compatibility in the version index (Chinese). Share only redacted error excerpts when requesting help. For client import and startup problems, see the FAQ.