diff --git a/README.md b/README.md index 686a7df..82114a3 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ **TCP-Native VPN. Works Where UDP Doesn't.** [![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red)](LICENSE) - [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Android%20%7C%20iOS-lightgrey)]() + [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20Android-lightgrey)]() [![Status](https://img.shields.io/badge/status-Beta-orange)]() @@ -33,7 +33,7 @@ Most VPNs treat TCP as a fallback. Konduit is designed for TCP from the ground u - **Userspace implementation** — no kernel modules, no root required - **Hot config reload** — update server configuration without dropping connections - **QR code provisioning** — scan once, connect instantly -- **Cross-platform** — Linux, macOS, Android, iOS +- **Cross-platform** — Linux, Windows, Android (macOS and iOS coming soon) - **Modern cryptography** — X25519 key exchange, ChaCha20-Poly1305 data channel - **Stealth mode** — port 443 deployment with decoy proxy for hostile network environments - **Memory safe** — written entirely in Rust @@ -42,11 +42,15 @@ Most VPNs treat TCP as a fallback. Konduit is designed for TCP from the ground u Releases are published on the [Releases](../../releases) page. Each release includes: -| Binary | Purpose | -|---|---| -| `konduit-server` | VPN server | -| `konduit` | CLI client (Linux) | -| `konduit-ctl` | Server provisioning tool | +| Artifact | Platform | Purpose | +|---|---|---| +| `konduit-server-*-linux-x86_64` | Linux | VPN server | +| `konduit-*-linux-x86_64` | Linux | CLI client | +| `konduit-ctl-*-linux-x86_64` | Linux | Server provisioning tool | +| `Konduit-*-x86_64.AppImage` | Linux | GUI client (AppImage) | +| `konduit-cli-*-windows-x86_64.zip` | Windows | CLI client + wintun.dll | +| `konduit-gui-*-windows-x86_64.zip` | Windows | GUI client | +| `konduit-*-android.aab` | Android | Android app (sideload via bundletool) | ### Linux (CLI) @@ -61,12 +65,34 @@ echo "your secret mantra" | ./konduit-ctl bootstrap -l vpn.example.com:443 -p - ./konduit connect --config client.toml ``` -### macOS · Android · iOS +### Linux (GUI) + +Download the `.AppImage`, make it executable, and run it: + +```bash +chmod +x Konduit-*-x86_64.AppImage +./Konduit-*-x86_64.AppImage +``` + +### Windows + +Extract the zip and run `konduit.exe` (CLI) or `Konduit.exe` (GUI). `wintun.dll` must remain alongside the executable. + +### Android + +Download from [Google Play](https://play.google.com/store/apps/details?id=eu.kaparulin.konduit) or sideload the `.aab` using [bundletool](https://github.com/google/bundletool). + +### macOS · iOS Coming soon. ## Setup +**GUI clients** +- [Linux GUI Quickstart](docs/gui-quickstart-linux.md) — AppImage, privileges, autostart +- [Windows GUI Quickstart](docs/gui-quickstart-windows.md) — extract, UAC, WinTun, autostart + +**CLI & server** - [Client Quickstart](docs/client-quickstart.md) — download, configure, connect, run as a systemd service - [Server Quickstart](docs/server-quickstart.md) — install, provision, NAT setup for iptables and firewalld - [Stealth Mode Setup](docs/stealth-setup.md) — HAProxy TCP passthrough + camouflage configuration diff --git a/docs/gui-quickstart-linux.md b/docs/gui-quickstart-linux.md new file mode 100644 index 0000000..531ff18 --- /dev/null +++ b/docs/gui-quickstart-linux.md @@ -0,0 +1,61 @@ +# Konduit GUI — Linux Quickstart + +## 1. Download + +Download the `Konduit-*-x86_64.AppImage` from the [Releases](../../releases) page. + +## 2. Make it executable + +```bash +chmod +x Konduit-*-x86_64.AppImage +``` + +## 3. Run + +Double-click the AppImage in your file manager, or launch it from the terminal: + +```bash +./Konduit-*-x86_64.AppImage +``` + +No installation required. The AppImage is self-contained. + +## 4. Load your config + +Your server administrator will provide a `client.toml` config file. On first launch, tap **Open config** and select the file. + +## 5. Privileges + +Konduit creates a TUN network device, which requires elevated network capability. The AppImage requests this automatically via a `pkexec` prompt on first run. If you see a password prompt, enter your user password to grant the capability. + +If `pkexec` is not available on your system (some minimal desktop environments), grant the capability manually once: + +```bash +sudo setcap cap_net_admin=+ep ~/.local/share/konduit/konduit-helper +``` + +## 6. Autostart on login (optional) + +To start Konduit automatically when you log in, enable autostart in the app: **Settings → Start on login**. + +Alternatively, copy the provided desktop entry to your autostart directory: + +```bash +cp ~/.local/share/applications/konduit.desktop ~/.config/autostart/ +``` + +## Troubleshooting + +**AppImage won't launch** — your system may be missing FUSE. Install it: + +```bash +# Debian / Ubuntu +sudo apt install libfuse2 + +# Fedora / RHEL +sudo dnf install fuse +``` + +**"Failed to create TUN device"** — the capability was not granted. Run the `setcap` command from step 5 and relaunch. + +**Config not found on relaunch** — the app remembers the last config path. If you move the file, use **Open config** again to reselect it. diff --git a/docs/gui-quickstart-windows.md b/docs/gui-quickstart-windows.md new file mode 100644 index 0000000..22acbd7 --- /dev/null +++ b/docs/gui-quickstart-windows.md @@ -0,0 +1,62 @@ +# Konduit GUI — Windows Quickstart + +## Requirements + +- Windows 10 or later (64-bit) +- Administrator account (required for VPN driver installation) + +## 1. Download + +Download `konduit-gui-*-windows-x86_64.zip` from the [Releases](../../releases) page. + +## 2. Extract + +Right-click the zip file and choose **Extract All**. Extract to a folder of your choice, for example `C:\Konduit`. + +Keep all files together — `Konduit.exe` and `wintun.dll` must be in the same folder. + +## 3. Run + +Double-click `Konduit.exe`. + +Windows will show a **UAC prompt** asking for administrator permission. This is required because Konduit uses the [WinTun](https://www.wintun.net/) driver to create a virtual network adapter. Click **Yes** to continue. + +> If you dismiss the UAC prompt, Konduit will not be able to establish a VPN connection. + +## 4. Load your config + +Your server administrator will provide a `client.toml` config file. On first launch, tap **Open config** and select the file. + +## 5. Connect + +Press **Connect**. A system tray icon will appear while the VPN is active. Right-click the tray icon to disconnect. + +## 6. Windows Defender / antivirus warning + +Some antivirus tools flag `wintun.dll` or new unsigned executables. If Windows Defender blocks the launch: + +1. Open **Windows Security → Virus & threat protection** +2. Click **Protection history** +3. Find the Konduit entry and choose **Allow** + +Alternatively, add the Konduit folder to your antivirus exclusion list. + +## 7. Autostart on login (optional) + +To start Konduit automatically when Windows starts, enable it in the app: **Settings → Start on login**. + +Alternatively, create a shortcut to `Konduit.exe` and place it in your Startup folder: + +``` +Win + R → shell:startup → paste shortcut here +``` + +## Troubleshooting + +**UAC prompt does not appear / app closes immediately** — make sure you are running as a user with administrator privileges. Standard (non-admin) accounts cannot install the WinTun driver. + +**"wintun.dll not found"** — `Konduit.exe` and `wintun.dll` must be in the same folder. Do not move them separately. + +**Connection fails immediately** — check that your `client.toml` points to the correct server address and port. Contact your server administrator if you are unsure. + +**Tray icon disappears unexpectedly** — the app may have crashed. Check Windows Event Viewer or relaunch `Konduit.exe`.