alanrpost/nightjar

Purpose and execution model

Nightjar is a Windows desktop VPN client that converts imported proxy links into sing-box configurations and runs a system-wide TUN VPN. It supports VLESS, Shadowsocks, Trojan, Hysteria2, and TUIC, with profile-based connection management, kill switch, autostart, reconnect behavior, and application split tunneling.

Primary launch/build entry points are run.py, app/main.py, and Nightjar.spec. The application is packaged for Windows with installer.iss.

Desktop application shell

app/main.py owns application startup and the primary GUI lifecycle. app/tray_app.py provides system-tray interaction, allowing connection control after the main window is hidden or closed. UI workflows are implemented as dialogs rather than a web/API layer, including profile editing and raw JSON editing.

Relevant paths:

• app/main.py

• app/tray_app.py

• app/edit_profile_dialog.py

Profile ingestion and persistence

Connection links enter through clipboard or QR import, are parsed into normalized profile data, then persist in the local profile store. Protocol detection is automatic based on the imported URI scheme. Profile management is the boundary between user-facing configuration and sing-box-specific runtime configuration.

Relevant paths:

• app/qr_import.py

• app/profile_parser.py

• app/profile_store.py

sing-box configuration compilation

app/singbox_config.py translates a selected normalized profile plus application settings into the sing-box JSON configuration. This is the key adapter boundary: the rest of Nightjar works with its own profile/settings model, while sing-box receives its required outbound, TUN, routing, DNS, and logging configuration.

Relevant paths:

• app/singbox_config.py

• app/profile_parser.py

• app/settings.py

VPN process lifecycle and privileged networking

app/singbox_manager.py owns launching, monitoring, stopping, and recovering the external sing-box process. It is the core runtime control plane for connect/disconnect and operational status. TUN mode requires administrator privileges; startup elevation and cleanup of stale processes are handled outside the normal UI flow.

Relevant paths:

• app/singbox_manager.py

• app/autostart.py

• app/cleanup.py

Traffic policy and connection features

Traffic handling is expressed through generated sing-box routing policy. Split tunneling selects applications whose traffic receives special routing treatment; the kill switch and full-tunnel TUN behavior protect or redirect system traffic. GeoIP data can support geographic/routing decisions. Runtime statistics and speed testing feed connection visibility in the desktop UI.

Relevant paths:

• app/split_tunnel_dialog.py

• app/geoip.py

• app/stats.py

Local platform integration and state

The application is Windows-specific in its packaging, installation, elevation, process handling, and autostart behavior. app/paths.py centralizes filesystem locations, including the documented %APPDATA%\vless-client\singbox.log runtime log location. Settings, persisted profiles, and generated/runtime artifacts remain local; the principal external runtime is the sing-box executable/process rather than a hosted service.

Relevant paths:

• app/paths.py

• app/settings.py

• installer.iss