OpenFlux
English | Русский
Network stack research tool. IPv4 TCP/UDP tunnel with pluggable transports (including a signed JS scripting engine for writing new ones), a batched + zstd codec, and two exit-node backends (L3 raw forward / L4 gVisor proxy).
Disclaimer
The author of OpenFlux does not encourage the use of this project to bypass restrictions or violate the rules of any platform, and is not responsible for the final scenarios of how users apply this tool in real life or on the Internet. Any specific technical features of the application are nothing more than an architectural coincidence, created without any intent.
The project is entirely non-commercial, contains no paid features, hidden subscriptions, or commercial benefit.
The author is not responsible for forks, modifications, or derivative versions of OpenFlux created by third parties. Any changes added to a fork are the responsibility of its author.
The author is not responsible for:
- Any use of OpenFlux by third parties
- Consequences caused by the use of forks and modifications
- Damage resulting from derivative versions
- Violations committed using forks
The original code is provided as is, without any warranties.
Clients
| Platform | Download | Notes |
|---|---|---|
| macOS | build from source | CLI + utun L3 client (--inbound=tun, default on macOS) |
| Linux | build from source | CLI client (SOCKS5) / exit node (L3 or L4) |
| Windows | build from source | CLI client (SOCKS5, or --inbound=tun via Wintun - needs administrator) / exit node (l4, or l3 via QEMU - see docs) |
| Desktop | OpenFluxDesktop releases | Windows/macOS/Linux: full tunnel or SOCKS5/HTTP proxy, multi-transport sessions, encryption, an in-app node-deployment wizard over SSH |
| Android | OpenFluxAndroid releases | System-wide VPN or local SOCKS5, multi-transport sessions with failover, encryption, captcha handling in a built-in browser |
| Android | OpenFlux-Android releases | Fork: system-wide VPN or SOCKS5 proxy, multi-transport sessions, captcha handling, phone as exit node |
| iOS | TestFlight beta | System-wide VPN via Network Extension |
iOS app built by @saharev1 - full iOS client, TestFlight pipeline, system VPN support, DNS-over-TLS, and many stability fixes. HUGE thanks!
OpenFlux-Android built by @damnurmum - an Android client with a system-wide VPN and a local SOCKS5 proxy mode, connection profiles, multi-transport sessions with failover (direct included), SmartCaptcha and login handling in a WebView (the exit node's too, passed through the tunnel from its address), the phone as an l4 exit node, Kill Switch and per-app and per-domain routing. Also contributed end-to-end encryption (#38), the Mail.ru transport (#60) and session resilience with exit captcha handling (#93) to this repository. HUGE thanks!
OpenFluxAndroid and OpenFluxDesktop run a Compose Multiplatform app and a shared module (multi-transport sessions, encryption, the built-in browser for captcha, the SSH node-deployment wizard) originally written by @meepo161 in OpenFluxClient and moved into these repositories with his agreement. HUGE thanks!
Android app - p1neappleXpress/OpenFluxAndroid, desktop app - p1neappleXpress/OpenFluxDesktop, the module they share - p1neappleXpress/OpenFluxClientShared.
How it works
Client (any): macOS (utun) / Linux / Windows / iOS (packet tunnel) / Android
|
v
Transport (Yandex.Docs / Volga / Board / MAX / Cups / Mail.ru / Direct / script)
|
v
Exit node --> Internet
--mode l3 (raw SNAT/DNAT, Linux + root)
--mode l4 (gVisor proxy, any platform)
Any client works with either exit backend; --mode is chosen on the exit
node, not the client. l3 forwards raw TCP/UDP with SNAT/DNAT and stays
end-to-end (Linux + root only); l4 terminates TCP/UDP in a userspace
gVisor stack and re-dials the real server (any OS, no root). A
multi-transport session can run several transports at once and fail over
between them. Full depth: docs/architecture.md.
Quickstart
go mod tidy
go build -o openflux .
# Exit node, L4 backend (any OS, no root)
./openflux --role=exit --mode=l4 --transport=yandex --url="YOUR_YANDEX_DOC_URL"
# Client, SOCKS5 (point a browser at 127.0.0.1:1080)
./openflux --role=client --inbound=socks5 --transport=yandex --url="YOUR_YANDEX_DOC_URL"See docs/architecture.md for the l3 (root,
Linux-only, faster) backend and the macOS/Windows full-tunnel clients, and
docs/cli-reference.md for every flag.
Highlights
- Pluggable native transports - Yandex.Docs, Yandex Volga, Yandex Board, MAX/OneMe, Cups.online, Mail.ru Docs, Direct.
- Scripted transports - a signed JS engine (
transport/script, goja) for writing new transports without touching Go or rebuilding the core. See docs/scripted-transports.md. - Multi-transport sessions with authenticated negotiation, encryption and failover. See docs/sessions.md.
- Two exit backends -
l3(raw SNAT/DNAT) andl4(gVisor proxy). See docs/architecture.md. - Mode without a server - the exit can be a small PHP program on any web hosting instead of a VDS. See docs/phpbox.md.
- Node provisioning wizard -
--node-wizardinstalls an exit on a VDS over SSH, non-interactively, from a desktop app. See docs/node-provisioning.md. - Shareable links and QR codes - an
openflux://link carries a full client configuration. See docs/links.md. - Captcha handling, batched + zstd codec (with a legacy per-packet fallback), optional AES-256-GCM encryption, and benchmark modes for raw goodput. See docs/transports.md and docs/architecture.md.
Read next
- docs/architecture.md - the client/exit diagram, the two exit backends, the repo layout, and current limitations.
- docs/transports.md - the native transport list, codec selection, captcha handling, and how to add a native one.
- docs/scripted-transports.md - the JS transport engine: the host API, signing and trust, the dev tools.
- docs/sessions.md - multi-transport sessions,
.conffiles, authenticated negotiation and encryption. - docs/links.md - the
openflux://link/QR format. - docs/node-provisioning.md - the SSH node wizard.
- docs/phpbox.md - the no-VPS PHP-hosting exit.
- docs/logging.md -
-d/-dd/-dddand--sensitive. - docs/cli-reference.md - every flag, flat.
- docs/building-and-releases.md - CI, tagged releases, exit-node releases, and the nightly channel.
Wire-level protocol framing lives at PROTOCOL_NEGOTIATION.md (linked from the docs above where it's relevant, not duplicated here).
What's in this repo
docs/- the guides above.transport/- every transport (native and scripted) and the session manager.tunnel/- the client-side virtual NIC and both exit backends.provision/- the SSH node-provisioning backend and the no-VPS PHP deployer.deploy/- the VDS installer script and the PHP exit's own sources.share/- theopenflux://link format.socks5/,netbind/,utils/- the SOCKS5 server, Windows interface binding, and logging.mobile/,ios-app/- the Android/iOS bridges and the SwiftUI iOS app..github/workflows/- CI and the three release channels (tagged, exit-node, nightly).
Requirements
- Go - see
go.modfor the exact version. - Android NDK r27+ / Xcode 26.6+ - only for the mobile client binaries.
- A Linux VPS / VDS for a VPS-hosted exit node (not needed for the
no-VPS PHP exit - docs/phpbox.md).
l3needs root;l4doesn't.
Status
The core tunnel path (native transports, the l3/l4 exit backends,
multi-transport sessions, encryption/negotiation) is CI-tested on every
push and has shipped across several tagged releases - see
CHANGELOG.md. The scripted-transport engine and the no-VPS PHP exit are
newer and still gaining real-world coverage; a Windows/macOS native l3
exit backend is not implemented yet (the working fallback is l4 on both).
The nightly prerelease channel (.github/workflows/nightly.yml) tracks
the nightly branch for anyone who wants a current build ahead of the
next tagged release.
License
GNU General Public License v3.0 or later. See LICENSE for the full text.
Third-party licenses are listed in NOTICE.
