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
Что это такое?OpenFlux — исследовательский инструмент сетевого стека: он строит IPv4-туннель TCP/UDP со сменными транспортами, батч-кодеком с zstd и двумя вариантами выходного узла («сырой» L3-проброс и L4-прокси на базе gVisor).
Клиент один или приложений несколько, под разные платформы?Это семейство приложений с общим ядром: CLI на Go для macOS/Linux/Windows, а также отдельные приложения для Desktop, Android и iOS, которые переиспользуют общий модуль Compose Multiplatform (OpenFluxClientShared) — сессии, шифрование и браузер капчи.
Как его запустить?На macOS/Linux/Windows CLI-клиент собирается из исходников с помощью Go. Либо можно скачать готовую сборку Desktop для полноценного туннеля или прокси SOCKS5/HTTP, установить приложение Android, которое работает как системный VPN, либо вступить в iOS-бету через TestFlight.
Чтобы собрать проект, нужен установленный Go? А для мобильных приложений — особые SDK?Для сборки ядра нужен Go (точная версия закреплена в go.mod); для сборки бинарников мобильного клиента дополнительно требуются Android NDK r27+ или Xcode 26.6+.
На всех ли платформах доступен быстрый режим выхода через L3?Нет. L3 (raw SNAT/DNAT, сквозной режим) требует root и работает только на Linux; нативного L3-выхода для Windows/macOS пока нет, поэтому там используется откат на L4-прокси gVisor. Движок скриптовых транспортов и PHP-выход без VPS тоже появились недавно и ещё набирают практику реального применения.
Можно ли пользоваться не только на компьютере, но и на телефоне?Да — кроме CLI для macOS/Linux/Windows есть нативное приложение Android с общесистемным VPN или локальным режимом SOCKS5, а также приложение iOS (сейчас бета в TestFlight) с системным VPN через Network Extension.
Зачем туннель маскируется под сервисы Яндекса или Mail.ru?Его нативные транспорты выдают трафик за реальные российские веб-сервисы (Яндекс Документы, Yandex Volga, MAX/OneMe, Cups.online, Документы Mail.ru, Direct), причём в одной сессии может одновременно работать несколько транспортов с автоматическим переключением между ними при сбоях.
Можно ли поднять выходной узел, не арендуя VPS?Да — в docs/phpbox.md описан режим, при котором выходным узлом служит просто небольшая PHP-программа на обычном веб-хостинге вместо выделенного VDS.
Как передать другому человеку свою работающую настройку подключения?Ссылка вида openflux:// — её можно показать и как QR-код — содержит полную конфигурацию клиента (см. docs/links.md).
Можно ли добавить новый транспорт, не пересобирая ядро на Go?Да — движок подписанных JavaScript-скриптов (transport/script, построен на goja) позволяет создавать и подписывать новые транспорты, не трогая Go и без перекомпиляции.
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