net-bridge/README.md

VPN Share

VPN Share is an open-source Android-first project for sharing an Android phone's active VPN connection with nearby computers, tablets, and phones.

The product goal is simple for users: start the VPN they already trust on their phone, tap Share, pair the receiving device, and let the client route traffic through the phone automatically.

Current Status

This repository contains the production architecture, protocol specification, Android project scaffold, Rust core scaffold, and a Linux-first USB gateway prototype.

The first shippable milestone is:

• Android gateway app, Kotlin, minSdk 26.
• Rust vpnshare-core packet engine library.
• USB companion-client transport.
• Desktop client foundation for Windows, Linux, and macOS.
• Encrypted VSHP tunnel with QR/code pairing.

The current desktop binary provides USB sharing through the Android gateway. On Linux it can create a real vpnshare0 TUN interface and route normal OS/app traffic through the phone with sudo ./target/debug/vpnshare-desktop system-gateway. See docs/desktop-client.md.

Important Platform Constraint

VPN Share uses companion clients on receiving devices. This is required because stock Android only allows one prepared VpnService owner at a time. The phone gateway must preserve the already-running VPN app, so it does not create a second phone-side VPN.

The Android app opens normal network sockets from the gateway process. When an existing VPN app is the device default network, those sockets are routed through that VPN by Android. The gateway must not call VpnService.protect() for forwarded traffic, because protected sockets bypass VPN routing.

Repository Layout

apps/android/              Android application and feature modules
clients/desktop/           Desktop client CLI/service foundation
crates/vpnshare-core/      Packet, NAT, DNS, MTU, and gateway domain engine
crates/vpnshare-proto/     VSHP frame and pairing protocol primitives
crates/vpnshare-transport/ Transport abstraction shared by clients/gateway
crates/vpnshare-ffi/       C ABI surface for Android JNI integration
docs/                      Architecture, protocol, security, testing, roadmap

Build Notes

Rust validation:

cargo test --workspace

Android validation, once a healthy Gradle installation or wrapper is available:

gradle :apps:android:app:assembleDebug

License

Apache-2.0. See LICENSE.