OpenFlux README

The project's README from github.com/p1neappleXpress/OpenFlux. As one markdown file: README.md.

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:

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

  1. docs/architecture.md - the client/exit diagram, the two exit backends, the repo layout, and current limitations.
  2. docs/transports.md - the native transport list, codec selection, captcha handling, and how to add a native one.
  3. docs/scripted-transports.md - the JS transport engine: the host API, signing and trust, the dev tools.
  4. docs/sessions.md - multi-transport sessions, .conf files, authenticated negotiation and encryption.
  5. docs/links.md - the openflux:// link/QR format.
  6. docs/node-provisioning.md - the SSH node wizard.
  7. docs/phpbox.md - the no-VPS PHP-hosting exit.
  8. docs/logging.md - -d/-dd/-ddd and --sensitive.
  9. docs/cli-reference.md - every flag, flat.
  10. 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

Requirements

  1. Go - see go.mod for the exact version.
  2. Android NDK r27+ / Xcode 26.6+ - only for the mobile client binaries.
  3. A Linux VPS / VDS for a VPS-hosted exit node (not needed for the no-VPS PHP exit - docs/phpbox.md). l3 needs root; l4 doesn'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.

OpenFlux (p1neappleXpress/OpenFlux)

Searching Database…

2.2K ·GitHub
OpenFlux
What is this?OpenFlux is a network stack research tool that builds an IPv4 TCP/UDP tunnel with pluggable transports, a batched+zstd codec, and two exit-node backends (a raw L3 forwarder and a gVisor-based L4 proxy).
Is there one client or several apps for different platforms?It's a family of apps sharing one core: a Go CLI for macOS/Linux/Windows, plus separate Desktop, Android and iOS apps that reuse a shared Compose Multiplatform module (OpenFluxClientShared) for sessions, encryption and the captcha browser.
How do I get it running?On macOS/Linux/Windows you build the CLI client from source with Go; alternatively grab a prebuilt Desktop release for a full tunnel or SOCKS5/HTTP proxy, install the Android app for a system VPN, or join the iOS TestFlight beta.
Do I need Go installed to build it, or special SDKs for the mobile apps?Building the core requires Go (the exact version is pinned in go.mod); the mobile client binaries additionally need Android NDK r27+ or Xcode 26.6+.
Does every platform get the faster L3 exit mode?No. L3 (raw SNAT/DNAT, end-to-end) needs root and only runs on Linux; a native L3 exit for Windows/macOS doesn't exist yet, so those fall back to the L4 gVisor proxy. The scripted-transport engine and the no-VPS PHP exit are also newer and still gaining real-world coverage.
Can I run this on mobile as well as desktop?Yes - besides the CLI for macOS/Linux/Windows, there's a native Android app with a system-wide VPN or local SOCKS5 mode, and an iOS app (currently TestFlight beta) with system VPN via Network Extension.
Why does the tunnel mimic Yandex or Mail.ru services?Its native transports disguise traffic as real Russian web services (Yandex Docs, Yandex Volga, MAX/OneMe, Cups.online, Mail.ru Docs, Direct), and a session can run several transports at once with automatic failover between them.
Can I run an exit node without renting a VPS?Yes - docs/phpbox.md describes a mode where the exit is just a small PHP program on ordinary web hosting instead of a dedicated VDS.
How do I share a working connection setup with someone else?An openflux:// link, which can also be shown as a QR code, carries a full client configuration (see docs/links.md).
Can I add a new transport without rebuilding the Go core?Yes - the signed JavaScript scripting engine (transport/script, built on goja) lets you write and sign new transports without touching Go or recompiling.
What are similar projects?vk-turn-proxy, MasterHttpRelayVPN-RUST, SoftEtherVPN, streisand, mhr-cfw, hysteria, brook, shadowsocks-c
Which topics is it in?compose-multiplatform, vps, qr-code, swiftui, anti-censorship, reverse-proxy, censorship-circumvention, ssh, vpn, encryption, proxy, gplv3
Creator
p1neappleXpress
Size
59.7 MB
Stars
2.2K
Updated
CommitOct 13Releasev0.13.0Oct 16
Age
3mo
Commits · 90 Days