Candlelight

Candlelight is a cross-platform desktop client for managing proxy and VPN profiles. It uses a Qt 6 interface, runs the networking core as a separate process, and communicates with it through gRPC.

The project is based on the Nekoray/Throne lineage and focuses on a cleaner desktop experience, practical routing tools, traffic visibility, scheduler/scenario automation, and a bundled sing-box/Xray-based core.

Screenshot

Features

• Modern Qt desktop UI for Windows, Linux, and macOS.
• Separate core process: CandlelightCore is launched and controlled by the GUI through gRPC.
• System proxy and TUN modes with quick switching from the main window.
• Profiles and subscriptions with groups, import/export, and support for common share formats.
• Routing and DNS tools for route profiles, rule sets, fake DNS, DNS hijacking, and direct/remote DNS strategies.
• Operational tools including traffic statistics, connection list, geo tests, scheduler, scenarios, updater, and helper executable.
• Local-first storage using SQLite for profiles, groups, settings, routes, scheduler data, and traffic history.

Supported protocols

• SOCKS
• HTTP(S)
• Shadowsocks
• Trojan
• VMess
• VLESS
• TUIC
• Hysteria / Hysteria2
• AnyTLS
• NaiveProxy
• Juicity
• TrustTunnel
• ShadowTLS
• WireGuard
• SSH
• Tailscale
• Custom outbound
• Custom config
• Chained outbounds
• Extra core

AmneziaWG profile import and editing are available in the Qt layer, but runtime connectivity depends on matching support in the bundled core build.

Architecture

Qt 6 GUI                              Go core
MainWindow, controllers, dialogs      CandlelightCore
Profiles, settings, SQLite       ->   gRPC server
Dashboard, scheduler, scenarios       sing-box / Xray integration
System proxy / TUN controls           routing, DNS, TUN, stats

Important entry points:

• src/main.cpp — GUI application entry point.
• src/ui/mainwindow.cpp — main window setup and actions.
• src/api/RPC.cpp — gRPC client wrapper.
• core/server/main.go — core executable entry point.
• core/server/server.go — gRPC server.
• src/database/ and include/database/ — SQLite repositories and migrations.

See docs/README.md for the documentation index and repowiki/ for extended architecture notes.

Repository layout

candlelight/
├── core/server/      # Go networking core
├── src/              # C++/Qt implementation
├── include/          # C++ headers and Qt .ui files
├── res/              # icons, styles, translations, resources
├── tests/            # parser, database, scheduler, scenario, UI tests
├── docs/             # project documentation and screenshots
├── repowiki/         # extended architecture notes
├── script/           # development and packaging scripts
├── cmake/            # platform CMake fragments
└── 3rdparty/         # vendored libraries

Releases

Prebuilt Windows artifacts are published on the GitHub Releases page:

• CandlelightSetup-<version>.exe — installer build.
• Candlelight-<version>-windows-x64.zip — portable build.

Build requirements

• CMake 3.20 or newer.
• C++20 compiler supported by Qt 6.
• Qt 6 with Widgets, Network, LinguistTools, and platform modules.
• Go toolchain for core/server.
• Windows builds can use Ninja and sccache automatically when available.

Building on Windows

Use the project build script:

build_windows.bat --help
build_windows.bat --no-core --no-deploy

For a full build including the Go core and Qt deployment:

build_windows.bat --full

The script defaults to Ninja and sccache when they are installed. Set CANDLELIGHT_USE_NINJA=0 or CANDLELIGHT_USE_SCCACHE=0 to disable those integrations.

Building manually

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Build the core separately when needed:

cd core/server
go build -o CandlelightCore .

More platform-specific details are documented in docs/build.md.

Testing

ctest --test-dir build_tests_mingw --output-on-failure

See docs/testing.md for test structure and fixtures.

Documentation

• docs/README.md — documentation index.
• docs/project-structure.md — repository and module map.
• docs/components.md — C++/Qt component overview.
• docs/go-core.md — Go core, proto, and gRPC notes.
• docs/database.md — SQLite schema and migrations.
• docs/build.md — build and packaging instructions.
• docs/testing.md — test layout and commands.
• docs/CONTRIBUTING.md — contribution guidelines.
• docs/SECURITY.md — security and sensitive-data policy.
• docs/RELEASE.md — release checklist.
• repowiki/ — extended architecture and data-flow documentation.

Contributing

Issues and pull requests are welcome. Please read docs/CONTRIBUTING.md before submitting changes.

Security notes

• Do not commit real proxy credentials, private keys, UUIDs, PSKs, subscription URLs, or local profile databases.
• TUN, system DNS, system proxy, updater, and helper operations can require elevated privileges depending on the platform.
• Antivirus tools may flag proxy/VPN software or self-updaters because they manipulate network settings and replace executables during updates.

Credits

• sing-box
• Xray-core
• Qt
• Qv2ray
• simple-protobuf
• fkYAML
• quirc
• QHotkey

License

See LICENSE.