NuggetVPN

NuggetVPN is a modern, lightweight, and fast VPN client built with Tauri v2 and React 19. It utilizes sing-box as its core engine to provide robust and secure connectivity.

Features

• High Performance: Built with Rust and React for minimal resource usage.
• Protocol Support:
  • VLESS: Supports Reality and TLS security flows.
  • Shadowsocks: Standard support for SS protocols.
  • And others!: We support all protocols that are implemented in sing-box
• Profile Management:
  • Import profiles via URL (Subscription).
  • Manually add profiles via vless:// or ss:// links.
  • Persistent profile storage.
• Real-time Logging: View connection logs directly in the app.
• System Integration:
  • Automatic TUN interface creation.
  • DNS hijacking prevention.
  • Self-elevation (macOS) for necessary privileges.
• Split Tunneling: You can set what domains or apps to proxy.
• Custom sing-box configs: You can set your own sing-box config.

Prerequisites

Before you begin, ensure you have the following installed:

• Rust: Install Rust (latest stable).
• Bun: Install Bun (or Node.js/npm/pnpm).
• Build Tools:
  • macOS: Xcode Command Line Tools (xcode-select --install).
  • Linux: build-essential, libwebkit2gtk-4.0-dev, libssl-dev, libgtk-3-dev, libayatana-appindicator3-dev, librsvg2-dev.
  • Windows: C++ build tools and WebView2.

Installation & Development

1. Clone the repository

   git clone https://github.com/Rigby-Foundation/NuggetVPN.git
   cd NuggetVPN

2. Install Frontend Dependencies

   bun install

3. Setup Sidecar (Important) NuggetVPN requires the sing-box binary to function. You must place the platform-specific binary in the src-tauri/bin/ directory.

   • Download sing-box from GitHub Releases.
   • Rename the binary to sing-box-<target-triple> (e.g., sing-box-aarch64-apple-darwin for Apple Silicon).
   • Place it in src-tauri/bin/.
   • Ensure it has execution permissions (chmod +x).

   Note: The tauri.conf.json expects the binary name to be just sing-box in the configuration, but Tauri's sidecar mechanism requires the target triple suffix on the actual file.

4. Run in Development Mode

   bun tauri dev

   Note: On macOS/Linux, the app may request administrative privileges (sudo) to create the TUN interface.

Building for Production

To build the application for your OS:

bun tauri build

The output will be in src-tauri/target/release/bundle/.

Troubleshooting

"App is damaged and can't be opened" (macOS)

Since this app is not signed with an Apple Developer Certificate (to keep it free and open-source), macOS Gatekeeper may block it. To fix this:

1. Open Terminal.
2. Run the following command:

   xattr -cr /Applications/NuggetVPN.app

   (Replace /Applications/NuggetVPN.app with the actual path if you installed it elsewhere)

Project Structure

• src/: React frontend application.
  • lib/: Some shadcn libs.
  • hooks/: shadcn/ui hooks.
  • components/: Reusable UI components.
• src-tauri/: Rust backend and Tauri configuration.
  • src/lib.rs: Main application logic, commands, and VPN management.
  • capabilities/: Tauri permission configurations.
  • bin/: External binaries (sing-box).

License

This project is licensed under the GPL-3.0 License.