fscarmen/sing-box: a one-click multi-protocol server script for VPS deployments

What fscarmen/sing-box actually installs on a VPS

This is a server-side installer, not a client. The repository is a Shell project whose main entry point is sing-box.sh, with config.conf, docker_init.sh, a Dockerfile and a force_version file alongside it. Running the script on a VPS produces a sing-box configuration with one or more inbound protocols drawn from Reality, Hysteria2, TUIC, Trojan, Shadowsocks, AnyTLS, ShadowTLS, Vmess, VLESS and NaiveProxy. The README describes the project as a one-click multi-protocol script and lists Argo tunnels plus subscriptions for Clash, V2rayN, Throne, ShadowRocket and SFA as part of the package.

The intended user is someone who has a VPS and wants an endpoint they can paste into a client, without assembling sing-box JSON themselves. The README states that no domain is required, which matters because Reality and the Argo tunnel paths remove the certificate-and-DNS work that a plain TLS setup would demand. If you are looking for the sing-box core itself, or a GUI, this is the wrong repository: the topics list mihomo, nekobox, v2rayn and shadowrocket because those are the clients the generated subscriptions target, not because the project ships them.

How the script builds a working sing-box configuration

The layout is a single Bash script plus a config file. sing-box.sh is the main script, with config.conf and force_version alongside it. The Dockerfile shows the container path: it builds on alpine:latest, unpacks s6-overlay for process supervision, then in the runtime stage installs wget, nginx, bash and openssl, creates /sing-box/cert, /sing-box/conf, /sing-box/subscribe and /sing-box/logs, and runs ./init.sh as the command. nginx is also installed in the image.

The changelog describes an evolution toward editing a live installation rather than reinstalling. Version 1.3.17 added SIGHUP hot-reload, replacing restart sequences with reload, and states that upgrades force the base config to be regenerated so that sing-box check passes. Version 1.3.20 lets you set independent, non-consecutive ports per protocol, but only after installation, so the install flow stays unchanged. Version 1.3.21 pre-registers a WARP account during install with a shared-key fallback, and lets you change it later through sing-box check plus SIGHUP. The pattern is consistent: the interactive install stays simple, and complexity moves into the sb -d menu.

Installing fscarmen/sing-box and bringing up a first node

The README's table of contents points to a section titled Sing-box for VPS 运行脚本, and the repository's entry point is sing-box.sh at the top level. Clone or fetch the repository, then execute the main script:

chmod +x sing-box.sh
./sing-box.sh

The script is interactive. It asks for the protocol set, ports, and the server address; per version 1.3.20 the server address accepts an IP or a domain, and the changelog suggests a DDNS domain for NAT VPS instances whose public IP changes daily. After the installer finishes, the management menu is reachable the same way, and the README refers to it as sb -d. That menu is where post-install changes live: setting independent per-protocol ports (1.3.20), toggling subscriptions on and off (1.3.18), binding outbound traffic to a specific NIC with bind_interface (1.3.16), and switching the Hysteria2 ignore_client_bandwidth toggle that version 1.3.25 added with a default of off.

For a container deployment the repository ships a Dockerfile and a docker_init.sh. The Dockerfile copies docker_init.sh to /sing-box/init.sh, makes it executable, and sets CMD [ "./init.sh" ], with configuration expected under /sing-box/conf and certificates under /sing-box/cert. The README has a section for Docker and Docker Compose installation, but the compose file itself is not among the repository's top-level files, so read that section before assuming a compose file ships in the repository root.

The sb -d menu is the real interface, and it is also the constraint

Almost everything that makes this project usable happens after installation. The install flow is deliberately kept unchanged by later features, which is why version 1.3.20 restricted independent per-protocol ports to the post-install editor. That design keeps first-run simple, but it means the script, not you, owns the shape of the configuration. Version 1.3.17 states that upgrades force the base config to be regenerated to the new format; if you have hand-edited the generated files, an upgrade is the moment those edits are at risk.

Some restrictions are explicit. Version 1.3.22 makes Hysteria2 Realm and port hopping mutually exclusive, with confirmation prompts in both the installer and sb -d before switching.

Where the script stops being the right answer

If you need a client, this repository is not it. The topics include v2rayn, nekobox, mihomo and shadowrocket because the script emits subscription formats for those clients, not because it replaces them. Someone searching for sing-box on iOS, Windows or Android is looking for a different piece of software.

If you operate many servers, the interactive model works against you. There is no configuration file you can template and commit with confidence: the script generates the configuration, and upgrades regenerate the base config. A declarative setup, where you write the sing-box JSON yourself and keep it in version control, gives you a reviewable diff and a predictable upgrade, at the cost of doing the Reality keys, certificate handling and subscription generation by hand. That is the real trade-off. This project optimizes for time-to-first-connection on one VPS; it does not optimize for fleet management or reproducible infrastructure.

A third boundary is protocol support in clients. If your client cannot import what the script exports, the server is running and useless to you.

Alternatives and what changes if you leave

The closest alternative is running sing-box directly from its own documentation. You install the core, write config.json, generate Reality keypairs and certificates yourself, and manage the service with systemd. The difference is ownership: you decide every field, upgrades do not rewrite your file, and nothing regenerates behind your back. The cost is that every protocol you add is another block of JSON, and subscription links for Clash, V2rayN or ShadowRocket become your problem. For one server, that is a few hours; for twenty, it is a different project.

A second path is the container route without the installer. The Dockerfile here already demonstrates it: s6-overlay plus the sing-box binary plus your own config directory. You keep the supervision and image packaging and drop the interactive script. That is a reasonable middle ground if you want containers but not generated configuration.

Maintenance, licence and what an upgrade costs

The repository is not archived and its last push was on 2026-10-31. The changelog is dense and recent: 1.3.29 on 2026.10.31, 1.3.28 on 2026.10.22, 1.3.27 on 2026.10.13. The repository has no published GitHub releases, so version tracking happens through the changelog and the force_version file rather than through tagged releases. That is a practical difference: you cannot pin an upgrade to a release artifact and read its notes; you track the README changelog.

The licence is GPL-3.0, stated in the repository and in the README's table of contents under 开源证书. If you redistribute a modified version, GPL-3.0 carries obligations that a permissive licence does not; that is a question for your own counsel, not something this article can settle. The README also carries a disclaimer section, which is worth reading before deploying anything.

The upgrade cost is the part to plan for. Because version 1.3.17 forces base-config regeneration on upgrade, an upgrade is not a no-op: it rewrites the generated base configuration to the current format. If you rely on values you set through sb -d, verify they survived. If you edited files directly, expect to redo that work.

Editorial conclusion

Adopt it if you already have a VPS and want a working multi-protocol sing-box endpoint with subscriptions without hand-writing JSON; the install is interactive, the config editor is the sb -d menu, and the last push was on 2026-10-31. Do not adopt it if you need a client application, a stable configuration format you control line by line, or a project with a published release history: the repository has no published releases, and the changelog notes that upgrades force the base config to be regenerated to the new format. Before committing, verify on a throwaway VPS that sing-box check passes after install, that your node ports are reachable through the firewall, and that the client you actually use can import the subscription link the script generates.

Frequently asked questions

Official sources

1. fscarmen/sing-box on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README