Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Neutron Documentation Wiki

Welcome to the Neutron technical documentation and developer wiki.

Neutron is a high-performance WireGuard manager for Linux written in Rust, leveraging NetworkManager as the system-native networking control plane.

Wiki Contents

1. Usage Guide (TUI & CLI)

Complete interactive guide to the Terminal User Interface (TUI), keybindings, modal navigation, and scriptable CLI command reference.

2. System Architecture & Design Principles

Detailed overview of the decoupled subsystem architecture, module boundaries, data flows, thread model, and comparative analysis of UI frontends (CLI, TUI, GUI, Electron).

3. NetworkManager Integration

How Neutron interfaces with NetworkManager, nmcli command execution, batch error aggregation, profile discovery, interface comment extraction, and connection lifecycle.

4. Security Architecture (Kill Switch & Lockdown)

Comprehensive explanation of the two security layers: Layer 3 NetworkManager policy routing (fwmark, exclusive DNS priorities) and Netfilter/Firewalld always-on OUTPUT filtering.

5. Split Tunneling (IP & Domain Routing)

Architecture of global split tunneling, Include vs. Exclude routing modes, CIDR normalization (/32 & /128), client-side DNS resolution, and NetworkManager route injection.

6. NAT-PMP Port Forwarding Engine

Pure Rust UDP implementation of the NAT-PMP protocol (RFC 6886), tunnel gateway derivation, mapping request framing, lease renewal timers, and clipboard integration.

7. User Configuration & Theming (config.toml)

Specification for the human-readable TOML configuration, managed profile drop directory (profiles/) auto-sync, built-in themes (Osaka Jade, Catppuccin, Nord, Gruvbox, Monochrome), and color customization.

8. Packaging & Universal Distribution

Packaging guides and distribution models for Homebrew tap formulas, Arch Linux AUR, and static musl compilation for headless servers.

9. Implementation Notes

Startup selection, checked activation, configuration persistence, and saved versus effective policy state.

10. Testing & Quality Checks

Formatting, Clippy, host tests, and disposable NetworkManager/firewall sandbox tests.

Core Invariants

  • NetworkManager as Single Source of Truth: All WireGuard profile parameters and secrets remain stored exclusively inside NetworkManager profile storage.
  • Decoupled Business Logic: No domain logic (routing, firewall, config, port forwarding) is coupled to GTK or terminal drawing code.
  • Apply-Before-Persist: Network operations are executed first; persisted application configurations are only updated if the underlying network mutation succeeds.
  • Fail-Safe Security: Kill Switch and Lockdown teardowns are strictly surgical and guaranteed never to lock the user out permanently.