How gui-for-cores/gui.for.singbox works
Purpose and Runtime
GUI.for.SingBox is a cross-platform desktop GUI for configuring and operating the Sing-box proxy core. It is built with Wails: a Go native host embeds a Vue frontend. The primary native entry point is main.go; application/window packaging is defined in wails.json and platform metadata under build/.
Desktop Host and Native Bridge
The Go bridge package exposes OS-facing capabilities to the frontend through generated Wails bindings. Its responsibilities include process execution, filesystem I/O, networking, MMDB handling, local server support, system proxy integration, and tray behavior.
• bridge/bridge.go
• bridge/exec.go
• bridge/system_proxy.go
• bridge/tray.go
• frontend/src/bridge/wailsjs/go/bridge/App.js
The frontend should use its typed bridge wrappers rather than invoke native APIs directly:
• frontend/src/bridge/index.ts
• frontend/src/bridge/exec.ts
• frontend/src/bridge/io.ts
Frontend Bootstrap and Application Shell
Vue starts at frontend/src/main.ts, mounts frontend/src/App.vue, and initializes lifecycle/bootstrap behavior before rendering the shared desktop shell. The shell owns navigation, title-bar behavior, splash state, and globally mounted modal/message overlays.
• frontend/src/main.ts
• frontend/src/App.vue
• frontend/src/hooks/useAppBootstrap.ts
• frontend/src/components/_common/AppShell.vue
Routing and Feature Domains
Client-side routes divide the app into operational domains: dashboard/control, profiles, subscriptions, rulesets, plugins, scheduled tasks, and settings.
• frontend/src/router/routes.ts
• frontend/src/views/HomeView/index.vue
• frontend/src/views/ProfilesView/index.vue
• frontend/src/views/SettingsView/index.vue
Profiles expose structured Sing-box configuration editing for inbounds, outbounds, DNS, routing, rules, rulesets, and mixin/script content:
• frontend/src/views/ProfilesView/components/ProfileEditor.vue
• frontend/src/views/ProfilesView/components/DnsConfig.vue
• frontend/src/views/ProfilesView/components/RouteConfig.vue
State, Persistence, and Configuration Flow
Pinia-style stores represent application settings, environment state, profiles, subscriptions, rulesets, plugins, task definitions, logs, and kernel API state. Views edit domain entities through these stores; persistence and native filesystem actions cross the frontend/native bridge boundary.
• frontend/src/stores/app.ts
• frontend/src/stores/profiles.ts
• frontend/src/stores/kernelApi.ts
• frontend/src/stores/subscribes.ts
Configuration-oriented views and stores are the main control plane for generating or selecting the Sing-box runtime configuration; they are distinct from live kernel interaction.
Sing-box Kernel Control and Live Observability
The frontend has a dedicated API layer for communicating with the running core, including request and WebSocket channels. The home dashboard consumes this control/telemetry surface for connections, traffic, groups, logs, and quick actions.
• frontend/src/api/kernel.ts
• frontend/src/api/request.ts
• frontend/src/api/websocket.ts
• frontend/src/views/HomeView/components/ConnectionsController.vue
• frontend/src/views/HomeView/components/KernelLogs.vue
Native process management is the boundary between UI/kernel control and the installed or managed Sing-box executable:
• bridge/exec.go
• bridge/server.go
• frontend/src/bridge/server.ts
External Dependencies and Delivery
Material runtimes are Go, Node.js/pnpm, Vue/Vite, and Wails. The app integrates with the operating system for system proxy and tray functionality, with Sing-box as the managed proxy kernel, and likely local/network endpoints through its kernel HTTP/WebSocket clients. Release and rolling-release automation are GitHub Actions workflows.
• go.mod
• frontend/package.json
• .github/workflows/release.yml
• .github/workflows/rolling-release.yml
Main entry points: bridge.go Native bridge · routes.ts Feature routes · index.ts Typed bridge wrappers · index.vue Dashboard
Components 17
Native Host
Go/Wails host and OS integration.
- Wails host · Embeds and launches the desktop application.
main.go - Native bridge · Exposes native capabilities through Wails bindings.
bridge/bridge.go - Process manager · Starts and manages the Sing-box process.
bridge/exec.go - Local server support
bridge/server.go - System proxy and tray
bridge/system_proxy.go
Vue Frontend
Desktop UI, state, and kernel control.
- Vue bootstrap · Initializes Vue and application lifecycle.
frontend/src/main.ts - Application shell · Owns navigation, title bar, splash, and global overlays.
frontend/src/App.vue - Feature routes · Routes operational feature domains.
frontend/src/router/routes.ts - Profile editor · Edits structured Sing-box configuration.
frontend/src/views/ProfilesView/components/ProfileEditor.vue - Domain stores · Hold settings, profiles, subscriptions, rulesets, plugins, tasks, and logs.
frontend/src/stores/profiles.ts - Typed bridge wrappers · Frontend boundary for native filesystem and execution actions.
frontend/src/bridge/index.ts - Kernel API client · Controls and observes the running core.
frontend/src/api/kernel.ts - Dashboard · Shows live connections, traffic, logs, and quick actions.
frontend/src/views/HomeView/index.vue
Managed Runtime
Sing-box execution and live API surface.
- Sing-box kernel · Runs the selected generated proxy configuration.
- Kernel HTTP/WebSocket · Exposes runtime control and telemetry.
Other components
- Operating system · Provides system proxy, tray, filesystem, and process facilities.
- Release automation · Builds release and rolling-release artifacts.
.github/workflows/release.yml
Connections 21
- Wails host → Native bridge: binds
- Wails host → Vue bootstrap: hosts
- Native bridge → Process manager: uses
- Native bridge → Local server support: uses
- Native bridge → System proxy and tray: uses
- Process manager → Sing-box kernel: launches and stops
- System proxy and tray → Operating system: integrates with
- Local server support → Operating system: uses
- Vue bootstrap → Application shell: mounts
- Application shell → Feature routes: renders route views
- Feature routes → Dashboard: selects
- Feature routes → Profile editor: selects
- Profile editor → Domain stores: edits configuration
- Dashboard → Domain stores: reads control state
- Domain stores → Typed bridge wrappers: persists via
- Typed bridge wrappers → Native bridge: Wails calls
- Typed bridge wrappers → Process manager: runtime commands
- Dashboard → Kernel API client: uses
- Kernel API client → Kernel HTTP/WebSocket: HTTP/WebSocket
- Kernel HTTP/WebSocket → Sing-box kernel: controls and streams
- Release automation → Wails host: packages