Control plane for sing-box. Manage kernel config, subscriptions, route/DNS policy, and runtime observability from a web panel.
PoC stage — APIs and data models may change.
- Configuration safety: dry-run, save, and restore reject path-level sing-box semantic/topology errors before disk writes or restarts; successful applies retain bounded local snapshots, path-level restore previews, validation, restart, and automatic rollback
- Dashboard: start/stop/restart kernel, setup checklist with failed-subscription previews, panel readiness diagnostics with retry, sing-box semantic config diagnostics with cross-layer outbound/DNS startup topology and feature summaries, sing-box 1.14 removed-field errors and deprecation diagnostics, and editor deep-links, rule-set file/cache freshness plus freshness-aware built-in updates, per-run diagnostics, and batch refresh, live health with failed-sub/unstable-node/apply-failure alerts and densified stream/apply errors, config apply timeline with error-code diagnostics, global outbound/Clash mode switching with latency diagnostics, live traffic/logs, memory
- Proxy config: structured inbound/outbound forms (TLS/Reality, transports), numeric field validation, list search, tag copy, ops deep-links to connections/logs/nodes, path-level save errors, Advanced JSON path-level save diff, dialog dry-run validate with path jump on failure
- Traffic policy: route/DNS rules with search, invert toggles, sing-box 1.14 interface-aware address matches, structured direct logical child rules with nested JSON fallback, structured inline headless rule sets, denser mobile cards, DNS servers with search, health probe, and error-code diagnostics; rule name/description stored by boxd; rule-set update error-code diagnostics; dry-run validate before apply; item path deep-links into rule/server dialogs with dialog dry-run validate; top-of-page route mode switch (rule / global direct / global proxy)
- Nodes & subscriptions: Clash YAML + base64 subscriptions, immediate first fetch and URL-change refresh, visible per-subscription refresh schedule, background refresh using per-subscription intervals, 16 MiB download guard, public HTTP(S)-only sources with private/local target and redirect protection, traffic/expiry, failed-first + retry with refresh/config-sync diagnostics, subscription deep-links to nodes/logs, denser mobile toolbars/cards, node search, latency color bands + history sparkline/detail chart, copyable probe errors with error-code hints, runtime groups, probes
- Observability: kernel/app logs with timestamps, copy/export, proxy-safe SSE heartbeats, and manual reconnect; TCP/UDP connections with source/network/inbound/process, live upload/download rates, search/sort/export, optimistic close, grouped views, and close-error diagnostics
- Advanced (grouped navigation: endpoints & services, certificates, shared resources, kernel options, configuration management): Endpoints with visual WireGuard peer editing, X.509 certificate trust stores and providers, sing-box CCM/OCM/DERP/Resolved/SSM API services, shared network namespaces and HTTP clients, kernel logging, NTP time sync, Experimental, full kernel JSON with path-level diff, local JSON import/export, read-only Tag/outbound/DNS/rule-set and DNS/outbound bootstrap-topology preflight, and searchable config-history audit/restore; dry-run validate on raw/endpoints/certificate/services/log/NTP/experimental; sticky save-error jump
- Auth (web deployments): densified login failures with error codes/hints and copyable diagnostics
- Page load diagnostics: shared densified query-load failures (code/hint/copy/retry) across dashboard, proxy, policy, nodes/subs, settings, and advanced pages
- Settings: theme, language, and log level persisted in DB; web deployments also expose password/JWT rotation; dirty-state save gates, probe URLs, global URLTest defaults, redacted support-bundle export, and panel backup export
- Terminal helper: copy http_proxy/https_proxy export commands for Bash/Zsh, Fish, PowerShell, and CMD, using the address from the detected mixed/HTTP/SOCKS inbound
| Layer | Choice |
|---|---|
| Backend | Go, chi, bbolt, statically linked sing-box |
| Business | internal/service transport-agnostic use-case layer (shared by HTTP handlers and desktop) |
| Frontend | React 19, TypeScript, Vite, shadcn/ui, Tailwind CSS |
| Auth | JWT (HS256), Argon2id passwords |
The embedded kernel targets sing-box 1.14.4. Editors support DNS response evaluation, VPN endpoints, Snell, bridge, and shared network namespaces / certificate providers / HTTP clients. Removed formats are reported in configuration diagnostics. See upgrade notes.
- Go 1.27.4+
- Node.js 20+
- Linux recommended for production
make build
BOXD_PASSWORD='your-strong-password' \
BOXD_DATA_DIR=./data \
BOXD_CONFIG=./data/config.json \
./bin/boxdOpen http://127.0.0.1:9091. Default username is admin. On the default password, the UI forces a password change.
First start creates complete defaults and starts a mixed proxy: 127.0.0.1:1080 on a host, 0.0.0.0:1080 inside a container. Empty configuration files and old minimal defaults are repaired with backups. Add nodes or a subscription to enable proxy traffic; until then proxy traffic stays blocked. The dashboard groups module preview/apply, client access, and start controls. TUN is an explicit, capability-checked choice; saved custom configurations and an explicit autostart setting are preserved. See default policy.
# Terminal 1: Vite UI (default http://127.0.0.1:5173)
cd ui && npm ci && npm run dev
# Terminal 2: API (default [::]:9091)
export BOXD_PASSWORD='dev-password'
export BOXD_DATA_DIR="$PWD/data"
export BOXD_CONFIG="$PWD/data/config.json"
export BOXD_CORS_ALLOWED_ORIGINS='http://127.0.0.1:5173,http://localhost:5173'
go run -tags with_clash_api ./cmd/boxd/GOFLAGS='-tags=with_clash_api' make dev starts the UI in the background and runs the backend for a quick smoke run.
- Sign in and rotate the admin password.
- Subscriptions / nodes: add a public HTTP(S) subscription URL or import VMess, VLESS, Trojan, Shadowsocks/SIP002, SSR, Hysteria/Hysteria2, TUIC, AnyTLS, or ShadowTLS links. Local/private sources and unsafe redirect targets are blocked. Subscriptions refresh in the background using each interval (the global interval is the fallback). Configure URLTest (inherit global defaults when needed). Downloads are capped at 16 MiB; refresh and config-sync failures expose actionable error codes. With URLTest disabled the group becomes a Selector: pick the exit node from either the subscription card or the outbound group card, and the choice is persisted as the group default. The persisted choice is authoritative and is reapplied after kernel start or reload, overriding stale sing-box cache state.
- Inbounds / outbounds: review the automatically created listeners and proxy group; add TUN with suitable privileges or customize listeners. Imported nodes and subscription groups automatically join the proxy selector.
- Route / DNS / Certificates / Services / Kernel logging / NTP / Experimental: customize the installed policy and optional trust stores, services, logging, and time sync. Unused optional modules are omitted from the default config.
- Dashboard: complete the four-step setup, preview and apply modules together, then validate/start the kernel when needed. Saving or importing preserves a stopped kernel; an active kernel reloads the new configuration.
- Settings: theme, language, minimum log level (stored in the database), system probe URLs, kernel autostart, redacted support-bundle export, and backup export.
- Terminal helper: copy the http_proxy/https_proxy export command for your shell; the proxy address comes from the mixed, HTTP, or SOCKS inbound.
Defaults hijack DNS, reject ads before allow rules, bypass LAN/ICMP, and split Chinese domains/IPs from proxy traffic. QUIC remains available. Four local rule sets are bundled: Loyalsoldier direct/proxy/reject lists and the MIT-licensed china-operator-ip IPv4/IPv6 list. Initial setup needs no downloads; updates use public HTTP(S) sources with a 16 MiB limit. Older SagerNet rule-set tags remain supported for existing configurations. Snapshot sources and licenses.
Panel Settings → Data backup downloads the same archive (auth required). Restore stays CLI-only.
./bin/boxd --backup /var/backups/boxd/boxd-$(date +%F).tar.gz
systemctl stop boxd.service # if running as a service
./bin/boxd --restore /var/backups/boxd/boxd-YYYY-MM-DD.tar.gz \
--data-dir /var/lib/boxd --config /etc/sing-box/config.json
systemctl start boxd.serviceThe archive database entry is boxd.db.
| Env | Flag | Default | Description |
|---|---|---|---|
BOXD_LISTEN |
--listen |
[::]:9091 |
Listen address (wins over BOXD_PORT) |
BOXD_PORT |
- | 9091 |
Port-only form |
BOXD_CONFIG |
--config |
/etc/sing-box/config.json (Linux); %ProgramData%\sing-box\config.json (Windows) |
Kernel config path |
BOXD_DATA_DIR |
--data-dir |
/var/lib/boxd (Linux); %ProgramData%\boxd (Windows) |
Data dir (DB, backups, rule-set cache) |
BOXD_USERNAME |
--username |
admin |
Login username |
BOXD_PASSWORD |
--password |
admin123 |
First-run password only; ignored once a hash exists |
BOXD_LOG_LEVEL |
--log-level |
info |
Application log level |
BOXD_REFRESH_INTERVAL |
--refresh-interval |
60 |
Fallback subscription refresh interval (minutes) |
BOXD_TLS_CERT |
--tls-cert |
- | TLS certificate path |
BOXD_TLS_KEY |
--tls-key |
- | TLS private key path |
BOXD_CORS_ALLOWED_ORIGINS |
- | - | Comma-separated CORS origins |
- Passwords: Argon2id in bbolt. Priority: stored hash → first-run
BOXD_PASSWORD→admin123. - JWT: secret generated on first start and stored in the DB; rotation from Settings invalidates all sessions.
- Default password keeps a persistent warning and forces rotation.
Nightly and formal release archives are published for both linux/amd64 and linux/arm64. Typical contents:
boxd— binaryboxd.service— systemd unitboxd.env.example— optional environment template (included when present in the repo)- docs / licenses
boxd itself does not auto-load a .env file. Configuration comes from:
- process environment variables (
BOXD_*) - CLI flags
- when run under systemd,
EnvironmentFile=-/etc/boxd/boxd.envinboxd.service(the leading-means “optional if missing”)
The Windows desktop application is packaged as an NSIS installer (boxd-desktop-<arch>-installer.exe). This provides a standard Windows installation experience with:
- Start menu and desktop shortcuts
- Uninstall entry in "Add or Remove Programs"
- Automatic WebView2 runtime installation (if missing)
- Installation directory selection
Installation:
- Download the appropriate installer (
boxd-desktop-amd64-installer.exeorboxd-desktop-arm64-installer.exe) - Run the installer and follow the wizard
- The application will be installed to
C:\Program Files\boxd-desktopby default
Silent installation:
boxd-desktop-amd64-installer.exe /S /D=C:\path\to\installDependencies:
- Windows 10 or later
- WebView2 Runtime (automatically installed if missing)
# 1. Unpack
tar -xzf boxd_v0.1.0_linux_amd64.tar.gz -C /tmp/boxd-release # or linux_arm64
cd /tmp/boxd-release
# 2. System user and directories
useradd --system --home /var/lib/boxd --shell /sbin/nologin boxd || true
install -d -o boxd -g boxd -m 0700 /var/lib/boxd
install -d -o root -g boxd -m 0750 /etc/boxd
install -d -o boxd -g boxd -m 0750 /etc/sing-box
# 3. Binary + unit + env
install -o root -g boxd -m 0750 ./boxd /usr/local/bin/boxd
install -m 0644 ./boxd.service /etc/systemd/system/boxd.service
if [[ -f ./boxd.env.example ]]; then
install -o root -g boxd -m 0640 ./boxd.env.example /etc/boxd/boxd.env
# set BOXD_PASSWORD and review other values
${EDITOR:-vi} /etc/boxd/boxd.env
else
printf '%s\n' 'BOXD_PASSWORD=your-strong-password' > /etc/boxd/boxd.env
chown root:boxd /etc/boxd/boxd.env
chmod 0640 /etc/boxd/boxd.env
fi
# 4. Start
systemctl daemon-reload
systemctl enable --now boxd.service
systemctl status boxd.serviceOpen http://127.0.0.1:9091 (or your listen address). Default username is admin.
export BOXD_PASSWORD='your-strong-password'
export BOXD_DATA_DIR=/var/lib/boxd
export BOXD_CONFIG=/etc/sing-box/config.json
/usr/local/bin/boxdOr pass flags:
/usr/local/bin/boxd \
--data-dir /var/lib/boxd \
--config /etc/sing-box/config.json \
--password 'your-strong-password'ICMP latency tests open raw sockets, which need the CAP_NET_RAW capability.
- systemd install:
boxd.servicealready setsAmbientCapabilities=CAP_NET_RAW; start viasystemctl start boxd.serviceand nothing more is needed. If you hand-roll your own unit, addAmbientCapabilities=CAP_NET_RAWandCapabilityBoundingSet=... CAP_NET_RAW. - Desktop package (rpm/deb, non-root run): the package
%postinstallgrantscap_net_raw+epautomatically. - Desktop manual install / AppImage: run
sudo ./scripts/grant-desktop-icmp.sh(resolves the desktop user GID automatically), orsudo ./scripts/grant-desktop-icmp.sh $USER setcap. - Direct binary run without systemd: launch as root, or grant the capability to the service user. Without it, ICMP tests fail with
icmp raw socket requires CAP_NET_RAW(TCP/HTTP tests are unaffected).
podman build --format docker --build-arg VERSION=local -t localhost/boxd:local .
podman run -d --name boxd --restart unless-stopped --http-proxy=false \
-p 127.0.0.1:9091:9091 -p 127.0.0.1:1080:1080 \
-e BOXD_PASSWORD='your-strong-password' \
-v boxd-data:/var/lib/boxd -v boxd-config:/etc/sing-box \
localhost/boxd:localOpen http://127.0.0.1:9091. Base modules are initialized and started automatically; explicit HTTP/SOCKS proxy mode needs no TUN privilege. Import nodes or a subscription, then point clients at 127.0.0.1:1080 with remote DNS resolution such as socks5h. The Docker image format preserves health checks, which Podman’s default OCI format discards.
Public images (after CI push):
# Nightly from main
docker pull ghcr.io/xuthus5/boxd:nightly
# Formal release
docker pull ghcr.io/xuthus5/boxd:latest
docker pull ghcr.io/xuthus5/boxd:v0.1.0docker run -d --name boxd --restart unless-stopped \
-p 127.0.0.1:9091:9091 -p 127.0.0.1:1080:1080 \
-e BOXD_PASSWORD='your-strong-password' \
-e BOXD_LISTEN='[::]:9091' \
-v boxd-data:/var/lib/boxd \
-v boxd-config:/etc/sing-box \
ghcr.io/xuthus5/boxd:latestNotes:
- Pass config via
-e BOXD_*(or--env-file); the container process does not read/etc/boxd/boxd.envby itself. - Persist
/var/lib/boxd(database, caches) and/etc/sing-box(kernel config). - TUN requires
--cap-add NET_ADMIN --device /dev/net/tunand explicit selection in module setup; address families follow detected capabilities. - TUN in a bridge container only captures that container’s traffic. Host transparent proxying needs a separate host-network and client/gateway routing design.
NET_RAWis required for ICMP latency tests (raw sockets). The container process runs as root so the capability applies; omit it to disable ICMP tests.- Health checks use
/readyzfor panel/config readiness; kernel state and proxy connectivity are separate checks.
docker build --build-arg VERSION=dev -t boxd:local .
docker run --rm -p 127.0.0.1:9091:9091 -p 127.0.0.1:1080:1080 -e BOXD_PASSWORD='dev-password' boxd:localFor binary installs, prefer Install from release archive. For containers, see Podman / Docker.
Built-in TLS:
BOXD_TLS_CERT=/etc/boxd/tls/fullchain.pem \
BOXD_TLS_KEY=/etc/boxd/tls/privkey.pem \
/usr/local/bin/boxdOr terminate TLS with Caddy / Nginx / Traefik, keep upstream on 127.0.0.1:9091, and pass through WebSocket/SSE.
Release gates and rollback: docs/boxd/release-checklist.md, docs/operations.md.
| Trigger | Binary | Docker (GHCR) |
|---|---|---|
| Pull request | quality checks only | build smoke (push: false) |
Push to main |
rolling nightly GitHub Release + Actions artifacts (boxd_nightly_linux_amd64/arm64.tar.gz, boxd_nightly_windows_amd64/arm64.tar.gz, boxd_nightly_darwin_amd64/arm64.tar.gz; desktop: boxd-desktop-windows, boxd-desktop-macos) |
multi-arch ghcr.io/<owner>/boxd:nightly (linux/amd64, linux/arm64) |
Tag v* |
formal GitHub Release + SBOM (linux/amd64, linux/arm64) |
multi-arch ghcr.io/<owner>/boxd:<tag>, :<version>, :latest |
Headless binaries are published for Linux (linux/amd64, linux/arm64), Windows (windows/amd64, windows/arm64) and macOS (darwin/amd64, darwin/arm64) as .tar.gz archives with sha256 checksums. The desktop app is published for Linux (deb/rpm/AppImage), Windows (zip) and macOS (zip, DMG best-effort). Nightly Linux deb/rpm packages carry a monotonically increasing version (0.1.0.<UTC date>.<UTC time>), so dnf upgrade always picks up the new build.
Examples (replace owner):
# Nightly image
docker pull ghcr.io/xuthus5/boxd:nightly
# Stable release image
docker pull ghcr.io/xuthus5/boxd:latest
docker pull ghcr.io/xuthus5/boxd:v0.1.0Nightly binary archives are published under the rolling GitHub Release tag nightly and also uploaded as workflow artifacts (14-day retention). Formal builds are produced by pushing a v* tag.
make build # UI build + embed + bin/boxd
make install-desktop # build desktop, install to /usr/local/bin, grant cap_net_raw
make dev # quick split run
make clean # remove bin and dist
make check-go # tests, race, coverage ≥90%, lint, govulncheck
make check-ui # typecheck / lint / coverage / build
make check-embedded-ui # embedded asset integrityFrontend:
cd ui
npm ci
npm run dev
npm run check
npm run e2e:install && npm run e2e # Playwright mocks; does not hit production :9091Backend:
go run ./cmd/boxd/
go test ./...
golangci-lint run ./...
goimports-reviser -rm-unused -set-alias -project-name github.com/xuthus5/boxd -recursive ./internal
goimports-reviser -rm-unused -set-alias -project-name github.com/xuthus5/boxd -recursive ./cmd./scripts/package-release.sh v0.1.0 release
# produces release/boxd_v0.1.0_linux_amd64.tar.gz, release/boxd_v0.1.0_linux_arm64.tar.gz, and sha256 filesPackage the headless (web service) boxd into deb/rpm/AppImage for amd64 and arm64:
./scripts/package-linux.sh v0.1.0 amd64 arm64
# produces build/linux/bin/boxd_v0.1.0_linux_<arch>.deb|.rpm|.AppImageBuild the desktop binary (requires GTK4 + WebKitGTK 6.0):
make build-desktop
# produces desktop/bin/boxd-desktop
# install locally; re-grants cap_net_raw after replacing the binary
# (install/cp drop file capabilities, which breaks routing_mark outbounds)
make install-desktopDesktop UI stability: if the WebKit renderer process dies (e.g. after
suspend/resume), the app reloads the page automatically and offers a
tray Reload UI fallback; WEBKIT_DISABLE_DMABUF_RENDERER=1 is set
by default on Linux to avoid known GPU crash paths.
Package the desktop app into a binary, deb/rpm/AppImage plus a .desktop entry
(arm64 builds run natively on an arm64 host/runner):
./scripts/package-desktop.sh v0.1.0 amd64
./scripts/package-desktop.sh v0.1.0 arm64
# produces desktop/bin/boxd-desktop, boxd-desktop.deb, boxd-desktop.rpm, boxd-desktop-<arch>.AppImageThe desktop app runs the sing-box core in-process (embedded mode, data in ~/.local/share/boxd), or connects to a remote boxd service (BOXD_DESKTOP_MODE=remote). It exposes a system tray, native windows, file dialogs, autostart, and URL scheme deep links; the React frontend auto-detects the desktop runtime and uses Wails bindings and events instead of HTTP/SSE. When launched by autostart, the app stays hidden in the tray (--hidden) instead of opening a window.
The native window frame is disabled; the lime panel header acts as the draggable title bar and provides in-app minimise, maximise/restore, and close controls.
The desktop UI has no login screen, logout action, or account password/JWT settings. Embedded mode opens the panel directly, while web deployments keep the existing authentication and security controls.
Formal release builds disable WebView developer tools (Wails production tag); nightly builds keep them enabled for debugging.
Windows builds can be code-signed to avoid SmartScreen warnings. The signing process uses a PKCS#12 certificate (.pfx) and a timestamp server.
Prerequisites:
- A valid code signing certificate (
.pfxor.p12format) - The certificate password
signtool.exe(Windows SDK) orosslsigncode(cross-platform)
Configuration:
Set the following GitHub Actions secrets:
CODESIGN_CERT: Base64-encoded certificate file (base64 -w 0 certificate.pfx)CODESIGN_PASSWORD: Certificate passwordTIMESTAMP_URL(optional): Timestamp server URL (default:http://timestamp.digicert.com)
Local signing:
# Set environment variables
export CODESIGN_CERT=/path/to/certificate.pfx
export CODESIGN_PASSWORD='your-password'
export TIMESTAMP_URL='http://timestamp.digicert.com'
# Run Windows packaging script (signing will be attempted)
./scripts/package-desktop-windows.sh v0.1.0 amd64Manual signing:
# Using signtool (Windows SDK)
signtool sign /f certificate.pfx /p "$PASSWORD" /tr http://timestamp.digicert.com /td sha256 /fd sha256 file.exe
# Using osslsigncode (cross-platform)
osslsigncode sign -pkcs12 certificate.pfx -pass "$PASSWORD" -tr http://timestamp.digicert.com -in file.exe -out file-signed.exeThe signing step is optional and will be skipped if secrets are not configured.
Pushing a v* tag runs the GitHub Release workflow (full gates, archive, SBOM).
BOXD_PASSWORD='your-password' ./scripts/e2e-live.sh
BOXD_PASSWORD='your-password' ./scripts/soak-runtime.shboxd first-party code is under Apache License 2.0.
Release binaries statically link GPL-3.0 sing-box / sing. Distributing those binaries also requires the GPL-3.0 obligations described in THIRD_PARTY_NOTICES.md (corresponding source and build information). This is not legal advice.
