# Welcome! So What Is S-UI?

> Imagine sing-box is a powerful but silent robot that routes internet traffic. S-UI is the friendly remote control you use to tell that robot what to do — through a web browser, not a command line. This opening page asks "why does this exist?" and maps out every other page in the wiki so you always know where to look next.

- Repository: alireza0/s-ui
- GitHub: https://github.com/alireza0/s-ui
- Human wiki: https://grok-wiki.com/public/wiki/alireza0-s-ui-2ddf594ac444
- Complete Markdown: https://grok-wiki.com/public/wiki/alireza0-s-ui-2ddf594ac444/llms-full.txt

## Source Files

- `README.md`
- `go.mod`
- `cmd/cmd.go`
- `install.sh`
- `Dockerfile`
- `s-ui.service`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:

- [README.md](README.md)
- [go.mod](go.mod)
- [main.go](main.go)
- [app/app.go](app/app.go)
- [cmd/cmd.go](cmd/cmd.go)
- [core/box.go](core/box.go)
- [install.sh](install.sh)
- [Dockerfile](Dockerfile)
- [s-ui.service](s-ui.service)
</details>

# Welcome! So What Is S-UI?

Imagine you bought a very powerful, very complicated piece of machinery — say, an industrial robot that can sort, route, and move things around in a warehouse. The robot is incredibly capable, but to give it instructions you have to write precise technical commands in a language only engineers understand. That's **sing-box**: a powerful, multi-protocol network proxy engine built by [SagerNet](https://github.com/SagerNet/sing-box) that routes your internet traffic through different paths and protocols — but it speaks in raw config files and command-line flags.

**S-UI is the friendly control panel you put on top of that robot.** It gives you a web browser interface where you can point, click, and configure — without ever touching a config file. It also watches the robot's health, tracks how much data each user is consuming, and can share connection settings with clients via subscription links. This page explains *why* S-UI exists, *how* its pieces fit together, and *where to look* in this wiki when you want to go deeper on any topic.

---

## The "Why" — What Problem Does S-UI Solve?

> *Why can't I just configure sing-box directly?*

You can! But sing-box is configured through a single big JSON file. Every time you want to add a new user, change a port, or swap a protocol, you have to:
1. Open the JSON file by hand.
2. Edit the right nested object in exactly the right syntax.
3. Restart sing-box.
4. Check logs to see if you made a typo.

If you manage more than one or two users, that process gets painful fast. S-UI replaces all of that with a web dashboard. It stores your configuration in a **SQLite database** ([`gorm.io/driver/sqlite`](go.mod#L17)), translates your clicks into a valid sing-box config, and then restarts the engine for you — all while showing you live traffic statistics and client status.

> *What is sing-box doing underneath?*

Sing-box is a universal proxy platform. It can speak many different protocols — VMess, VLESS, Trojan, Shadowsocks, Hysteria2, TUIC, SOCKS, HTTP, and more. S-UI lists these protocols in the README and wraps them all behind the same UI — you pick a protocol from a dropdown, and S-UI writes the correct JSON.

---

## The Architecture at a Glance

```text
┌─────────────────────────────────────────────────────┐
│                  Browser / Client                   │
│  (Web Panel at :2095/app)   (Subscription at :2096) │
└────────────────┬────────────────────┬───────────────┘
                 │  HTTP/HTTPS        │  HTTP/HTTPS
┌────────────────▼────────────────────▼───────────────┐
│                     S-UI Process  (sui binary)       │
│  ┌───────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ web.Server│  │sub.Server│  │   cronjob.CronJob│  │
│  │ (Gin API) │  │ (Gin API)│  │  (stats, cleanup)│  │
│  └─────┬─────┘  └────┬─────┘  └──────────────────┘  │
│        │             │                               │
│  ┌─────▼─────────────▼────────────────────────────┐ │
│  │         service layer (Go packages)             │ │
│  │  panel · config · inbounds · outbounds          │ │
│  │  clients · stats · tls · sub · warp             │ │
│  └─────────────────────┬──────────────────────────┘ │
│                        │                             │
│  ┌─────────────────────▼──────────────────────────┐ │
│  │         database  (SQLite via GORM)             │ │
│  └─────────────────────┬──────────────────────────┘ │
│                        │                             │
│  ┌─────────────────────▼──────────────────────────┐ │
│  │     core.Core  →  core.Box  (sing-box engine)  │ │
│  │     Manages inbounds / outbounds / routing      │ │
│  └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```

Sources: [app/app.go:18-53](), [core/box.go:38-55]()

---

## The Five Moving Parts

### 1. The `sui` Binary — One Process to Rule Them All

When you run S-UI, a single Go binary called `sui` starts up. Its `main()` function decides what to do based on how you called it:

```go
// main.go:42-49
func main() {
    if len(os.Args) < 2 {
        runApp()    // ← normal startup: web panel + sing-box
        return
    } else {
        cmd.ParseCmd()  // ← maintenance subcommands
    }
}
```

No arguments → the full app starts. With arguments → you get administrative subcommands.

Sources: [main.go:42-49]()

---

### 2. The App — Four Servers Working Together

`app.App.Start()` fires up four concurrent components:

| Component | What It Does | Default Address |
|---|---|---|
| `web.Server` | Serves the admin web panel (Gin HTTP framework) | `:2095/app/` |
| `sub.Server` | Serves client subscription links (JSON, Clash, plain links) | `:2096/sub/` |
| `cronjob.CronJob` | Periodic tasks: collect traffic stats, prune old data, check engine health | — (background) |
| `core.Core` / `core.Box` | Wraps sing-box itself: inbounds, outbounds, routing, DNS | — (configured ports) |

Sources: [app/app.go:56-88]()

---

### 3. The Core — A Direct sing-box Wrapper

The `core` package is where S-UI actually *talks* to sing-box. It does not shell out to a separate process — it embeds sing-box as a Go library (`github.com/sagernet/sing-box v1.13.12`) and manages its lifecycle directly.

The `Box` struct mirrors sing-box's internal architecture:

```go
// core/box.go:38-55
type Box struct {
    logFactory   log.Factory
    network      *route.NetworkManager
    inbound      *inbound.Manager
    outbound     *outbound.Manager
    dnsRouter    *dns.Router
    router       *route.Router
    statsTracker *StatsTracker
    connTracker  *ConnTracker
    ...
}
```

This means S-UI has direct access to live connection stats, traffic counters, and the routing table — no parsing of log files needed.

Sources: [core/box.go:38-55](), [go.mod:14]()

---

### 4. The Database — Where Your Config Lives

S-UI persists everything in a **SQLite** database via GORM. The database models live in `database/model/`:

| Model file | What it stores |
|---|---|
| `inbounds.go` | Inbound listener configs (protocol, port, tag) |
| `outbounds.go` | Outbound route configs |
| `endpoints.go` | Endpoint entries |
| `services.go` | Auxiliary services |
| `model.go` | Shared types: Users, Settings, Traffic stats |

When you save a change in the web panel, the service layer writes to SQLite, regenerates a sing-box config JSON in memory, and calls `core.Box` to reload.

Sources: [app/app.go:37](), [go.mod:17-18]()

---

### 5. The CLI — Admin Escape Hatch

If you get locked out of the web panel or need to automate setup, the CLI subcommands let you work directly without a browser:

| Command | What it does |
|---|---|
| `sui admin --show` | Print the first admin's username and password |
| `sui admin --reset` | Reset admin credentials |
| `sui admin --username X --password Y` | Set new credentials |
| `sui setting --port 8080 --path /panel/` | Change panel port/path |
| `sui setting --subPort 8081 --subPath /sub/` | Change subscription port/path |
| `sui uri` | Print the full panel URL |
| `sui migrate` | Run database migrations after an upgrade |
| `sui -v` | Print S-UI and sing-box versions |

Sources: [cmd/cmd.go:17-111]()

---

## How Installation Works

> *If I wanted to run this today, what actually happens?*

### The one-liner path (Linux/macOS)

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

The `install.sh` script:
1. Detects your OS (`/etc/os-release`) and CPU architecture.
2. Installs system prerequisites (`wget`, `curl`, `tar`, `tzdata`).
3. Downloads the correct pre-built `sui` binary for your platform.
4. Runs `sui migrate` to initialize the database.
5. Asks you to set a panel port, path, subscription port, and path.
6. Installs two systemd unit files: one for S-UI (`s-ui.service`), one for the sing-box engine.
7. Starts both services.

Sources: [install.sh:1-80]()

### The systemd unit

```ini
# s-ui.service
[Service]
WorkingDirectory=/usr/local/s-ui/
ExecStart=/usr/local/s-ui/sui
Restart=on-failure
RestartSec=10s
```

The service runs from `/usr/local/s-ui/` and auto-restarts on failure.

Sources: [s-ui.service:1-12]()

### The Docker path

The multi-stage `Dockerfile` shows the full build:
1. **Stage 1 (`front-builder`)**: `node:alpine` compiles the Vue.js frontend (`npm run build`).
2. **Stage 2 (`backend-builder`)**: `golang:1.26-alpine` compiles the Go binary with tags like `with_quic`, `with_grpc`, `with_utls`, `with_acme`, `with_gvisor` — enabling the full set of sing-box features.
3. **Stage 3 (final)**: `alpine` image ships the `sui` binary, `libcronet.so`, and the entrypoint.

```sh
docker run -itd \
    -p 2095:2095 -p 2096:2096 -p 443:443 -p 80:80 \
    -v $PWD/db/:/app/db/ \
    -v $PWD/cert/:/root/cert/ \
    alireza7/s-ui:latest
```

Sources: [Dockerfile:1-48]()

---

## What Protocols and Platforms Are Supported?

### Protocols (✓ VERIFIED from README)

| Category | Protocols |
|---|---|
| General | Mixed, SOCKS, HTTP, HTTPS, Direct, Redirect, TProxy |
| V2Ray-based | VLESS, VMess, Trojan, Shadowsocks |
| Other | ShadowTLS, Hysteria, Hysteria2, Naive, TUIC |
| Special | XTLS, WireGuard (via `wgctrl`) |

Sources: [README.md:211-215](), [go.mod:15]()

### Platforms (✓ VERIFIED from README)

| OS | Architectures | Status |
|---|---|---|
| Linux | amd64, arm64, armv7, armv6, armv5, 386, s390x | Fully supported |
| Windows | amd64, 386, arm64 | Fully supported |
| macOS | amd64, arm64 | Experimental |

Sources: [README.md:35-39]()

---

## Key Environment Variables

| Variable | Default | Purpose |
|---|---|---|
| `SUI_LOG_LEVEL` | `"info"` | Log verbosity (`debug`/`info`/`warn`/`error`) |
| `SUI_DEBUG` | `false` | Enable debug mode |
| `SUI_BIN_FOLDER` | `"bin"` | Where sing-box binary is looked for |
| `SUI_DB_FOLDER` | `"db"` | Where the SQLite database file lives |
| `SINGBOX_API` | — | Override the sing-box API endpoint |

Sources: [README.md:226-238]()

---

## Where to Go Next in This Wiki

Think of this page as the lobby. Here is every room and what you'll find there:

| Topic | What you'll learn |
|---|---|
| **Installation & Upgrade** | Detailed walk-through of the `install.sh` script, Docker Compose setup, and Windows installer |
| **Web Panel Tour** | The dashboard layout: inbounds, outbounds, clients, traffic stats, system status |
| **Inbounds & Clients** | How to create a listener, assign users, set data caps and expiry dates |
| **Outbounds & Routing** | Advanced traffic routing: PROXY Protocol, transparent proxy, split routing rules |
| **Subscription Service** | How the `:2096/sub/` server generates Clash configs, JSON configs, and plain links |
| **TLS & HTTPS** | Enabling HTTPS for the panel itself using Certbot or manual certs |
| **CLI Reference** | Every `sui` subcommand and flag, with examples |
| **API Documentation** | The REST API surface for automation and integration |
| **Environment Variables** | Full reference for `SUI_*` vars and `SINGBOX_API` |
| **Database & Backup** | Where data lives, how to back it up, how migrations work |
| **Development Setup** | Building frontend + backend from source, contributing a change |

---

## Summary

S-UI is a Go web application that wraps sing-box — the industry-grade proxy engine — in a browser-accessible control panel. It stores configuration in SQLite, talks to sing-box directly as an embedded library (not a subprocess), serves two HTTP endpoints (admin panel and subscription service), and runs background jobs for traffic accounting. The single `sui` binary is the entire program; the `install.sh` script installs it as a systemd service, and a Docker image is also available. Everything above was verified from the repository source; the entry point is [`main.go:13-49`](main.go) and the top-level orchestration lives in [`app/app.go`](app/app.go).