alireza0/s-ui: a Sing-Box web panel with a REST API and subscription service

What S-UI adds on top of Sing-Box

Sing-Box is a proxy platform. It is configured by files, and editing those files by hand is how most people start. S-UI is a web panel that sits in front of it: the repository is a Go application (module github.com/alireza0/s-ui, Go 1.26.7) that imports github.com/sagernet/sing-box v1.14.1 directly, so the panel and the proxy core share a codebase rather than talking over a config file you edit yourself.

The audience is narrow but real. If you run a single Sing-Box host and want to add, edit and disable inbounds from a browser, hand out subscription links to clients, and script changes through an API instead of SSH sessions, S-UI covers that. The README lists multi-protocol, multi-client inbound management, an advanced traffic routing interface, client and system status, subscription links in link, JSON and Clash formats, dark and light themes, and an API interface.

The README carries its own warning: the project is "only for personal learning and communication", with a request not to use it in a production environment. That sentence sits above the feature table, and it is the single most important line on the page. Treat the panel as an operator convenience for a host you control, not as a managed service platform.

How the panel, the core and the subscription service fit together

The repository layout tells most of the story. Top-level directories include api/, app/, cmd/, config/, core/, cronjob/, database/, middleware/, network/, service/, sub/, util/ and web/. The database layer is gorm.io/gorm v1.31.2 with gorm.io/driver/sqlite v1.6.0, so panel state lives in SQLite. The web layer uses gin-gonic/gin v1.12.0 with gin-contrib/sessions v1.1.1 for the panel UI, and go-chi/chi/v5 v5.3.2, which is the usual choice for the separate API surface. Scheduling comes from robfig/cron/v3. System metrics come from gopsutil/v4.

The protocol support is not hand-rolled. The go.mod file pulls in sing-vmess, sing-shadowsocks, sing-snell, sing-quic, sing-mux, sing-tun, sing-anytls, refraction-networking/utls and wireguard/wgctrl. That is the Sing-Box ecosystem assembled as libraries, which is why the panel can offer VLESS, VMess, Trojan, Shadowsocks, ShadowTLS, TUIC, Hysteria, Hysteria2 and NaiveProxy style inbounds without a separate core binary per protocol.

The subscription service is a distinct moving part with its own port and path. The README gives the default subscription port as 2096 and the path as /sub/, and points to three Wiki pages describing the URL formats, the JSON template keys and the Clash.Meta template with proxy groups and filters. The API is separate again: a token-authenticated REST interface under /apiv2, documented in the API Documentation Wiki page, with a Configuration Objects page describing the shape of what it reads and writes. Two surfaces, two auth models, one SQLite database.

Installing S-UI on Linux and reaching the panel

The primary path is a shell script served from the repository. The README shows the Linux and macOS command as a single line that pipes a curl download into bash. On a fresh host, that is the whole install.

bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/master/install.sh)

The installer is localized. The README states it ships in the same six languages as the panel: en (the default), fa, ru, vi, zhcn and zhtw. You pick one with the SUI_LANG environment variable, and when it is unset the installer uses your system $LANG as a hint. This is useful when the prompts appear in a language you do not read.

SUI_LANG=fa bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/master/install.sh)

After it finishes, the defaults from the README are: panel on port 2095 at path /app/, subscription service on port 2096 at path /sub/, and the user and password both set to admin. So the first thing you open is http://<host>:2095/app/ and the first thing you should do is change that credential. The README does not describe a forced password change on first login, so this is on you.

Alpine is handled separately. The README notes that the script detects Alpine, uses apk and OpenRC rather than apt and systemd, and that Alpine has no bash by default. Install it first, then run the same script. Service control is rc-service s-ui start|stop|restart, with rc-update add s-ui default for autostart.

Docker and docker compose for S-UI

The compose file in the repository is short and uses the published image alireza7/s-ui with container_name s-ui. It mounts two host directories, ./db and ./cert, into /app/db and /app/cert, publishes ports 2095 and 2096, sets restart: unless-stopped, and runs entrypoint.sh. The README's Docker steps create a directory, fetch the compose file and bring the stack up.

mkdir s-ui && cd s-ui
wget -q https://raw.githubusercontent.com/alireza0/s-ui/master/docker-compose.yml
docker compose up -d

The two volumes are the part worth thinking about before you run this. ./db holds the SQLite database, so it is your entire panel state: inbounds, clients, settings. ./cert holds certificates. If you delete that directory, you lose the panel configuration, and the README does not document an export or backup command for it. Copying the directory is the only backup mechanism the repository implies.

The Dockerfile explains a deliberate choice: base images are pinned by digest rather than by floating tag, with the comment that node:alpine and alpine resolved to whatever was published that day, so two builds of the same commit could differ. The build runs a Node stage for the frontend, a Go stage with CGO_ENABLED=1 that downloads libcronet.so from SagerNet/cronet-go, and a final alpine stage. That cronet download is a build-time dependency on a GitHub release URL, which is worth knowing if you build the image yourself behind a restrictive network.

Where S-UI is the wrong tool

The README's own disclaimer is the first limitation, and it is not boilerplate. A project that asks you not to run it in production is telling you its maintainers have not committed to the operational guarantees production implies. The README does not document rollback, does not describe a migration path for the SQLite schema between releases, and does not mention high availability or multi-node coordination. The panel is a single process against a single SQLite file. If your requirement is a control plane for several proxy hosts, S-UI as described here does not provide one.

Platform support is uneven. Linux covers amd64, arm64, armv7, armv6, armv5, 386 and s390x. Windows covers amd64, 386 and arm64. macOS is marked experimental for both amd64 and arm64. If you are on macOS, you are on the platform the project itself flags as not settled.

There is also an upgrade surface the README leaves open. It shows how to install a specific legacy version by appending the version to the install command, which is useful, but it does not say what happens to an existing SQLite database when you move between versions, or whether a downgrade is safe. If you pin a version and later want to go back, the README does not tell you how. That is a real risk for anyone who treats the panel as infrastructure rather than a learning exercise.

S-UI compared with 3x-ui

The obvious comparison is 3x-ui, which shows up in the related searches around this project. Both are web panels for proxy cores, but the core is the difference. S-UI is built on SagerNet/Sing-Box and imports it as a Go library, which is why the protocol list in the README spans Shadowsocks, ShadowTLS, VMess, VLESS, Trojan, TUIC, Hysteria, Hysteria2 and NaiveProxy through the sing-* modules in go.mod. 3x-ui is built around Xray. If your existing configuration, client mix or operational habits are Xray-shaped, S-UI is a rewrite of that layer, not a drop-in replacement, and the inbound objects and subscription output will not match what you have.

The second difference is the API. S-UI documents a token-authenticated REST interface under /apiv2 with separate Wiki pages for the API itself and for the configuration objects it reads and writes. That makes the panel scriptable without screen scraping. If you do not need an API and only want a UI, that surface adds nothing for you, and the smaller of the two projects may be less to maintain.

The third difference is the subscription service. S-UI runs it on its own port and path (2096 and /sub/) and emits three formats: link, JSON and Clash, with dedicated Wiki pages for the JSON and Clash.Meta templates. If your clients need Clash.Meta output with proxy groups and filters, that is a documented feature here rather than something you assemble yourself.

Licence and the cost of staying current

S-UI is GPL-3.0. That matters if you plan to modify it and distribute the result, because the licence carries obligations that permissive licences do not. It does not restrict running the panel on your own host, and this is not legal advice; read the licence text at the link the README gives if distribution is on your roadmap.

The maintenance picture from the repository is current: the last push was on 2026-09-16, and releases v1.6.3, v1.6.2 and v1.6.1 landed on 2026-09-16, 2026-09-13 and 2026-09-12. Three releases in five days suggests active work, though the README does not describe a release cadence or a support window, so you cannot infer how long a given version will keep working.

Upgrade cost is where the panel gets expensive. The install script fetches from the master branch, so a bare re-run tracks whatever is current rather than a version you chose. The README shows how to pin: set VERSION and append it to the install command. If you care about reproducibility, pin, and keep a copy of the ./db directory from the Docker deployment or /usr/local/s-ui from the systemd one before you upgrade. The uninstall instructions remove /usr/local/s-ui, /usr/bin/s-ui and the s-ui and sing-box service files, which tells you exactly which paths hold your state.

Editorial conclusion

Adopt S-UI if you already run Sing-Box and want a web layer for inbound management, subscription links and the /apiv2 REST API, and if you are comfortable with the README's own warning against production use. Do not adopt it if you need a panel that documents its rollback path, or if a single-node panel with no documented high-availability story will not fit your setup. Before installing, verify the panel port 2095 and subscription port 2096 are free, check that your platform is listed as supported rather than experimental, and read the Settings Reference in the Wiki so you know which defaults you are accepting.

Frequently asked questions

Official sources

1. alireza0/s-ui on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases