Skip to content
xuthus5Public

About

control plane for sing-box. Manage kernel config, subscriptions, route/DNS policy, and runtime observability from a web panel. sing-box 控制平面。提供 Web 面板管理内核配置、订阅节点、路由/DNS 策略与运行观测。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

boxd

English | 简体中文

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.

boxd

Features

  • 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

Stack

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.

Quick start

Requirements

  • Go 1.27.4+
  • Node.js 20+
  • Linux recommended for production

Build and run

make build
BOXD_PASSWORD='your-strong-password' \
  BOXD_DATA_DIR=./data \
  BOXD_CONFIG=./data/config.json \
  ./bin/boxd

Open 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.

Dev mode (split frontend/backend)

# 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.

Usage

  1. Sign in and rotate the admin password.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Settings: theme, language, minimum log level (stored in the database), system probe URLs, kernel autostart, redacted support-bundle export, and backup export.
  7. Terminal helper: copy the http_proxy/https_proxy export command for your shell; the proxy address comes from the mixed, HTTP, or SOCKS inbound.

Built-in routing helpers

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.

Backup and restore

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.service

The archive database entry is boxd.db.

Configuration

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

Auth notes

  • 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.

Install from release archive

Nightly and formal release archives are published for both linux/amd64 and linux/arm64. Typical contents:

  • boxd — binary
  • boxd.service — systemd unit
  • boxd.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:

  1. process environment variables (BOXD_*)
  2. CLI flags
  3. when run under systemd, EnvironmentFile=-/etc/boxd/boxd.env in boxd.service (the leading - means “optional if missing”)

Windows NSIS installer

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:

  1. Download the appropriate installer (boxd-desktop-amd64-installer.exe or boxd-desktop-arm64-installer.exe)
  2. Run the installer and follow the wizard
  3. The application will be installed to C:\Program Files\boxd-desktop by default

Silent installation:

boxd-desktop-amd64-installer.exe /S /D=C:\path\to\install

Dependencies:

  • Windows 10 or later
  • WebView2 Runtime (automatically installed if missing)

systemd install (recommended)

# 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.service

Open http://127.0.0.1:9091 (or your listen address). Default username is admin.

Run the binary without systemd

export BOXD_PASSWORD='your-strong-password'
export BOXD_DATA_DIR=/var/lib/boxd
export BOXD_CONFIG=/etc/sing-box/config.json
/usr/local/bin/boxd

Or pass flags:

/usr/local/bin/boxd \
  --data-dir /var/lib/boxd \
  --config /etc/sing-box/config.json \
  --password 'your-strong-password'

ICMP latency tests require network privilege

ICMP latency tests open raw sockets, which need the CAP_NET_RAW capability.

  • systemd install: boxd.service already sets AmbientCapabilities=CAP_NET_RAW; start via systemctl start boxd.service and nothing more is needed. If you hand-roll your own unit, add AmbientCapabilities=CAP_NET_RAW and CapabilityBoundingSet=... CAP_NET_RAW.
  • Desktop package (rpm/deb, non-root run): the package %postinstall grants cap_net_raw+ep automatically.
  • Desktop manual install / AppImage: run sudo ./scripts/grant-desktop-icmp.sh (resolves the desktop user GID automatically), or sudo ./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 / Docker

Build and run with Podman

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:local

Open 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.0

Run with Docker

docker 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:latest

Notes:

  • Pass config via -e BOXD_* (or --env-file); the container process does not read /etc/boxd/boxd.env by itself.
  • Persist /var/lib/boxd (database, caches) and /etc/sing-box (kernel config).
  • TUN requires --cap-add NET_ADMIN --device /dev/net/tun and 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_RAW is 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 /readyz for panel/config readiness; kernel state and proxy connectivity are separate checks.

Build the image locally

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:local

Deploy

For binary installs, prefer Install from release archive. For containers, see Podman / Docker.

TLS

Built-in TLS:

BOXD_TLS_CERT=/etc/boxd/tls/fullchain.pem \
BOXD_TLS_KEY=/etc/boxd/tls/privkey.pem \
/usr/local/bin/boxd

Or 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.

CI artifacts and Docker images

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.0

Nightly 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.

Local development

Day-to-day

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 integrity

Frontend:

cd ui
npm ci
npm run dev
npm run check
npm run e2e:install && npm run e2e   # Playwright mocks; does not hit production :9091

Backend:

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

Release package

./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 files

Package 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|.AppImage

Desktop app (Wails3)

Build 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-desktop

Desktop 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>.AppImage

The 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.

Code signing (Windows)

Windows builds can be code-signed to avoid SmartScreen warnings. The signing process uses a PKCS#12 certificate (.pfx) and a timestamp server.

Prerequisites:

  1. A valid code signing certificate (.pfx or .p12 format)
  2. The certificate password
  3. signtool.exe (Windows SDK) or osslsigncode (cross-platform)

Configuration:

Set the following GitHub Actions secrets:

  • CODESIGN_CERT: Base64-encoded certificate file (base64 -w 0 certificate.pfx)
  • CODESIGN_PASSWORD: Certificate password
  • TIMESTAMP_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 amd64

Manual 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.exe

The 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).

Live smoke

BOXD_PASSWORD='your-password' ./scripts/e2e-live.sh
BOXD_PASSWORD='your-password' ./scripts/soak-runtime.sh

License

boxd 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.

About

control plane for sing-box. Manage kernel config, subscriptions, route/DNS policy, and runtime observability from a web panel. sing-box 控制平面。提供 Web 面板管理内核配置、订阅节点、路由/DNS 策略与运行观测。

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages