NetF

Status: NetF 0.2.0 Windows release candidate under active validation. NetF is a fork of Netch, originally created by AmazingDM and its contributors. It is an independent application and is not an official Netch release.

NetF — Split tunneling for Windows preserves Netch's lightweight Windows proxy client behavior, including process-aware routing, TUN routing, network sharing, multiple proxy protocols, and reusable mode files. This fork exists to preserve those useful behaviors while making the project maintainable, testable, secure, and pleasant to use on current Windows systems.

The modernization is incremental. The existing WinForms application and native networking components remain the compatibility baseline while a Tauri 2 desktop shell and a UI-independent engine boundary are developed alongside them.

• The WinForms compatibility application now targets .NET 10 LTS; its C++ helpers and native behavior remain preserved.
• Existing Storage/mode files remain the compatibility format.
• A new Tauri desktop workspace lives in src/Netch.Desktop.
• The first modern vertical slice scans a directory tree for Windows executables and emits rules compatible with legacy process-mode files.
• The new scanner has deterministic output, skips directory links/reparse points, reports inaccessible paths, and enforces a configurable result limit.
• The desktop follows the Windows theme by default and also supports persisted light or dark appearance overrides.
• Compatible SOCKS5, Shadowsocks, VMess, VLESS, Trojan, and WireGuard profiles use the pinned Xray v26.3.27 provider. Unsupported imported profiles fail closed with an explanation; NetF does not silently invoke an unowned fallback.
• Generated Xray configurations are validated by the real core, and five TCP protocol paths are exercised with local end-to-end proxy traffic tests.
• Settings saves are flushed, re-read, validated, backed up, and atomically replaced instead of modifying the only configuration in place.
• A self-contained .NET 10 netf-engine-host.exe exposes an allowlisted JSON API to the Rust adapter. The compact Servers Connect / Library workspaces can create, edit, duplicate, confirm-delete, search, and connect supported profiles. Saved passwords, UUIDs, and private/pre-shared keys never return to React; edits use explicit Keep saved / Replace / Clear actions.
• Servers Library can paste one standard VLESS, VMess, Trojan, Shadowsocks, or SOCKS5 share link. Parsing is local and offline, the link is bounded to 8,192 characters and cleared after every attempt, and unsupported transports, plugins, TLS modes, duplicate parameters, or provider options fail closed.
• The connection mode picker is an accessible searchable combobox with visible results, keyboard selection, clear/Escape behavior, and fail-closed selection.
• The compact Modes Library searches and sorts the complete library alphabetically, marks built-in, imported, and user-owned modes, and edits Process/TUN rules. Built-ins use copy-on-customize; imported and user modes are backed up and atomically replaced. Compatible modes can be merged with deduplicated rules. Every origin can be deleted after confirmation while stopped/failed; deletion creates a flushed timestamped backup, and built-ins use a versioned tombstone so runtime preparation does not silently restore them.
• The Modes Scanner is a separate compact workspace, preserving bounded, deterministic executable discovery without keeping scanner state in the root UI.
• Overview reports engine/runtime readiness and mode ownership. Activity shows a bounded, credential-redacted log tail that can be copied for diagnostics.
• Settings exposes a validated operational subset of listener, redirector, Process child handling, TUN adapter/DNS, endpoint testing, and Xray behavior with atomic persistence and rollback.
• Servers can test one endpoint or the complete library with three bounded TCP or ICMP probes. Results distinguish success, timeout, DNS failure, and other errors without returning credentials. An optional 1–3600 second monitor tests only the connected server and is cancelled before disconnect or shutdown.
• Runtime verification and the engine handshake run off the desktop event loop, so the window remains responsive and reports the current startup stage.
• Overview makes stopped, transitioning, connected, failed, and unknown states explicit in text and color. The same state drives the sidebar, window title, Activity view, and notification-area icon.
• Closing the window hides NetF to the notification area by default. Settings can instead make window close use the same disconnect/cleanup path as explicit Exit NetF; cleanup failure keeps and restores the application. A second launch focuses the existing instance.
• Settings can register a verified per-user Windows Scheduled Task to start NetF in the tray at sign-in. Auto-start never connects automatically.

The modern desktop is functional, but privileged process/TUN/sharing behavior still requires the documented hands-on Windows VM and recovery matrix before 0.2.0 publication. Manual server management, modes, settings, tray lifecycle, and auto-start are enabled behind stopped-state and typed validation boundaries.

Modern desktop (Tauri 2 + React/TypeScript)
        |
        | typed Tauri commands and events
        v
Rust desktop controller + versioned EngineBackend API
        |
        | staged engine boundary
        v
Existing .NET orchestration + C++/driver helpers

The target is not a permanent stack of two application runtimes. The .NET engine boundary is a migration bridge: preserve behavior first, measure parity, then decide component-by-component whether a Rust port reduces risk and maintenance cost.

See architecture, the compatibility matrix, the modernization roadmap, and security notes before changing networking or privilege code. Operational failures are covered in troubleshooting and the Windows smoke test. See the measured performance review and ranked optimization backlog for this milestone.

• Windows 10 or later
• Microsoft C++ Build Tools with Desktop development with C++
• Microsoft Edge WebView2 Runtime
• Rust stable toolchain
• Node.js 22 LTS or newer

cd src\Netch.Desktop
npm install
npm run tauri:dev

tauri:dev builds the self-contained engine host, compiles the first-party Redirector and RouteHelper, assembles a checksum-manifested runtime template, and launches the desktop with administrator rights and no console window. On startup, the app verifies and installs those assets into its private local application-data directory.

The Servers tab can import data/settings.json and mode/Custom from a selected configuration directory. A one-click opt-in action also detects the previous NetF data under %LOCALAPPDATA%\org.netchfork.preview while the standalone app uses %LOCALAPPDATA%\io.github.amiradroit.netf. Import validates the data, creates a rollback backup, and uses atomic configuration replacement. It never copies or executes source binaries, DLLs, drivers, caches, logs, or geo assets. A SOCKS server is used directly; compatible VMess/VLESS/Trojan-family profiles use the packaged, checksum-pinned xray.exe. Unsupported legacy provider shapes remain visibly unavailable until an owned, audited compatibility provider is packaged.

For a single server, open Servers → Library, paste a share link, and choose Import link. Supported forms are standard vless://, Base64-JSON or authority-style vmess://, trojan://, SIP002 ss://, and socks5:// or socks:// URIs. This is deliberately not a subscription client: it accepts one URI, performs no network request, does not execute plugin options, and does not infer a non-standard WireGuard link. Add WireGuard through the typed manual form. The link contains credentials while it is in the paste box, so do not include it in screenshots or issue reports.

Run frontend checks without opening a desktop window:

cd src\Netch.Desktop
npm run check
npm run test

Run Rust tests:

cd src\Netch.Desktop\src-tauri
cargo test

The elevated all-features GUI test binary may require an elevated runner. The library suite, including real EngineHost IPC, can be run explicitly with cargo test --lib --all-features.

Build the complete debug executable without an installer:

cd src\Netch.Desktop
npm run tauri:build -- --debug --no-bundle

The output is src\Netch.Desktop\src-tauri\target\debug\NetF.exe. See Windows smoke testing before connecting a real profile.

Build the release installer and portable archive:

cd src\Netch.Desktop
npm run tauri:build
npm run package:portable

The installer is written under src-tauri\target\release\bundle\nsis; the portable archive is written to the repository deliverables directory. The portable package includes NetF.exe, netf-engine-host.exe, the verified runtime-template, README, GPL license, and upstream notice.

The compatibility build needs Visual Studio C++ build tools, .NET SDK 10.0.302 (pinned by global.json), Go, Rust, and the native build dependencies described by the existing scripts. build.ps1 downloads and compiles runtime components; review it before running it in a trusted environment.

.\build.ps1 -Configuration Release -OutputPath release

Run the .NET compatibility, provider-config, and loopback traffic tests with a checksum-verified Xray binary:

$xray = .\Other\xray-core\fetch.ps1
$env:NETCH_XRAY_PATH = $xray
dotnet test .\Tests\Tests.csproj -c Release

The release build packages Xray under its own filename and includes its MPL-2.0 license. It does not overwrite v2ray-sn.exe, so unsupported legacy profile shapes retain their existing fallback.

Packaged native/helper provenance, hashes, licenses, and update procedures are tracked in third_party/runtime-components.json. Components marked distribution-audit-required are suitable only for compatibility development; they block a public release until replaced or fully traced and licensed.

Legacy settings are stored under data/settings.json; mode definitions live under mode/ in a release and under Storage/mode/ in this repository. Do not point development builds at the only copy of a real configuration. Configuration saves create settings.json.bak, flush and re-read a temporary file in the same directory, validate it, and atomically replace the destination. Imported modes are kept under mode/Custom/Imported; modes created or cloned by the modern app live under mode/Custom/User. Re-import preserves the user-owned directory. Mode updates follow the same backup, temporary-file validation, and atomic replacement policy.

The modern runtime intentionally omits Xray geoip.dat and geosite.dat because NetF currently selects applications, not user domain/IP rule lists. It also omits inactive aiodns.conf because no aiodns helper is distributed. Pinned source/cache artifacts remain available for a future optional feature.

The frontend can request only two native folder actions: modes and appData. Rust resolves and validates both; React cannot provide a path.

The new scanner emits the same kind of C++ regex fragments as the old scanner: it uses executable filenames such as game\.exe, not absolute paths. The mode editor accepts one rule per line for Process and TUN modes. Share-mode arguments remain read-only because exposing arbitrary helper arguments to the webview would violate the command boundary.

Desktop-only settings are stored separately as desktop-settings.json under %LOCALAPPDATA%\io.github.amiradroit.netf. The old application-data directory is never modified during startup or import and remains a rollback source. The schema-v2 desktop file stores Windows auto-start and hideToTray/exit close behavior; schema-v1 files migrate atomically with safe hide-to-tray behavior. The engine settings retain their existing data/settings.json shape. NetF now round-trips child-process routing, TUN IPv4/netmask/gateway/custom-DNS fields, TCP-versus-ICMP endpoint checks, and the compatible StartedPingInterval value (-1/legacy 0 disabled, 1..3600 enabled). Endpoint latency measures DNS plus TCP/ICMP reachability, not proxy authentication or tunneled traffic. The auto-start toggle changes only the fixed NetF Startup Scheduled Task; the webview cannot supply an executable path, task name, or arguments. Verification normalizes quoted/device paths and checks the current Windows SID; stale registrations expose explicit repair/remove actions.

NetF performs administrator-level networking changes and loads inherited native code and a kernel driver. Treat release engineering as security-sensitive:

• do not download unsigned mutable binaries at runtime;
• pin source versions and verify hashes during builds;
• keep the webview capability allowlist narrow;
• never expose arbitrary shell execution to frontend code;
• redact proxy credentials from logs and diagnostics;
• sign release executables, helpers, and drivers where applicable.

See docs/security.md for the current threat model and known gaps.

This fork remains licensed under GNU GPL v3. Preserve LICENSE, Netch/NOTICE.txt, copyright notices, and source availability when distributing modified binaries. New code in this repository is distributed under the same GPL-3.0 license unless a file explicitly states otherwise.

NetF has distinct branding and does not represent itself as an official Netch release. Required credit to AmazingDM and upstream contributors remains in the collapsed About & legal view, documentation, license, notices, and source history.