Main Components of the OpenFlux Architecture: A Modular Bypass System

OpenFlux is built around four interchangeable modules—a command-line entry point, pluggable transport layer, TCP tunnel layer, and SOCKS5 server—that together provide a universal bypass/proxy solution with optional AES-256-GCM encryption and compression.

The p1neappleXpress/OpenFlux repository implements a modular networking tool designed to circumvent censorship through various cloud-based transport mechanisms. Understanding the OpenFlux architecture is essential for developers looking to extend its capabilities or deploy custom bypass solutions. The codebase follows a clean separation of concerns, allowing individual components to be swapped or modified without affecting the entire system.

Core Components of the OpenFlux Architecture

Command-Line Entry Point

The application lifecycle begins in main.go, which serves as the central orchestrator for the OpenFlux architecture. This component handles flag parsing, determines whether the binary runs as an exit node or client, and initializes the selected transport mechanism. According to the source code, the entry point also manages the wrapping of transports with encryption and compression layers when the -encryption-key-file flag is provided.

Transport Layer

The transport layer implements the actual network transport protocols that carry tunneled traffic. Located in the transport/ directory, this component defines a clean Transport interface in transport/transport.go that all implementations must satisfy. The OpenFlux architecture currently supports four distinct transports:

• Yandex Docs (transport/yandex/yandex.go) and Yandex Volga (transport/yandex/vyandex.go) – Uses Yandex cloud document storage for data exfiltration
• OneMe (transport/oneme/max_transport.go) – Implements authentication via maxToken and maxUid parameters
• Cupsonline (transport/cupsonline/cupsonline.go) – Alternative transport channel

Each transport can be dynamically wrapped with NewEncryptedTransport (AES-256-GCM) from transport/encrypted.go and CompressedTransport (gzip) from transport/compressor.go without modifying the underlying implementation.

Tunnel Layer

The tunnel layer provides reliable TCP connectivity abstraction through tunnel/tunnel.go and tunnel/packettunnel.go. The OpenFlux architecture supports two operational modes:

• Proxy Mode (default) – Works across all platforms by tunneling TCP connections through the selected transport
• Raw Mode (Linux only) – Requires root privileges and operates at the packet level using raw sockets (tunnel/rawsocket_linux.go), allowing for low-level packet manipulation and iptables integration

The tunnel implementation abstracts underlying socket implementations, enabling the same codebase to function on Linux, Windows, macOS, and iOS with platform-specific optimizations.

SOCKS5 Server

When running in client mode, OpenFlux exposes the tunnel to local applications via a standard SOCKS5 interface implemented in socks5/socks5.go. The server listens on port :1080 by default and forwards incoming SOCKS connections into the active tunnel, allowing standard applications to route traffic through the bypass system without modification.

How the Components Work Together

The modular design of the OpenFlux architecture follows a specific initialization sequence:

1. Flag parsing in main.go determines the operation mode (client vs. exit node) and selected transport protocol.

2. Transport instantiation creates the specific implementation (e.g., yandex.NewYandexDocsTransport, oneme.NewOneMeTransport) based on command-line flags.

3. Encryption wrapping occurs when -encryption-key-file is specified, wrapping the base transport with NewEncryptedTransport using AES-256-GCM encryption, followed by optional gzip compression.

4. Tunnel creation instantiates tunnel.NewTCPTunnelMode on top of the prepared transport stack, selecting between proxy mode or raw mode (Linux only).

5. Client mode activation starts the SOCKS5 server (socks5.NewSOCKS5Server) to accept local application connections and forward them through the tunnel.

6. Exit node mode places the binary in listening state, accepting inbound tunnel connections or manipulating iptables rules when operating in raw mode.

Implementation Examples

Running a Client with Yandex Docs Transport

./openflux -client -transport yandex -url https://yandex.com/doc/yourdoc

This command initializes the OpenFlux architecture in client mode using the Yandex Docs transport. The -client flag enables SOCKS5 mode on port 1080, while -transport yandex selects the implementation from transport/yandex/yandex.go.

Deploying an Exit Node in Raw Mode

sudo ./openflux -exit-node -mode raw -local-ip 10.0.0.2

Raw mode requires root privileges and activates the low-level packet handling from tunnel/rawsocket_linux.go. The -local-ip parameter configures the egress IP address and triggers the iptables rules that suppress outbound RST packets for that address.

Enabling Transport Encryption

./openflux -client -transport oneme -maxToken AB1234 -maxUid 5678 \
    -encryption-key-file ./secret.key

The -encryption-key-file flag triggers the wrapping logic in main.go (lines 94-107) to apply AES-256-GCM encryption via transport.NewEncryptedTransport before establishing the tunnel.

iOS Packet Tunnel Integration

// In PacketTunnelProvider.swift (ios-app/OpenFluxTunnel/PacketTunnelProvider.swift)
let tunnel = OpenFluxTunnel()
try tunnel.startTunnel(options: [:])

The iOS implementation reuses the core OpenFlux architecture through Go mobile bindings, exposing the same transport and tunnel logic through the Network Extension framework with a thin Swift wrapper.

Key Source Files Reference

• main.go – CLI entry point and component wiring
• transport/transport.go – Core transport interface definition
• transport/yandex/yandex.go – Yandex Docs transport implementation
• transport/oneme/max_transport.go – OneMe transport with authentication
• transport/cupsonline/cupsonline.go – Cupsonline transport implementation
• transport/encrypted.go – AES-256-GCM encryption wrapper
• transport/compressor.go – GZIP compression wrapper
• tunnel/tunnel.go – High-level tunnel orchestration
• tunnel/rawsocket_linux.go – Linux-specific raw socket implementation
• socks5/socks5.go – SOCKS5 proxy server implementation
• ios-app/OpenFluxTunnel/PacketTunnelProvider.swift – iOS Network Extension bridge

Summary

• The OpenFlux architecture consists of four primary components: command-line entry point, pluggable transport layer, TCP tunnel layer, and SOCKS5 server.
• Transports are interchangeable implementations of the Transport interface located in transport/transport.go, supporting Yandex Docs, OneMe, and Cupsonline protocols.
• The tunnel layer supports both high-level proxy mode (cross-platform) and low-level raw mode (Linux only with root privileges).
• Optional AES-256-GCM encryption and gzip compression can be applied to any transport without modifying the underlying implementation.
• The modular design allows new transports to be added by implementing a single interface and registering the new component in main.go.

Frequently Asked Questions

What transports does OpenFlux support?

OpenFlux currently implements four transport mechanisms: Yandex Docs and Yandex Volga (cloud document storage), OneMe ( authenticated via token/UID pairs), and Cupsonline. Each transport resides in its own subdirectory under transport/ and implements the common Transport interface defined in transport/transport.go.

How does OpenFlux handle encryption?

When the -encryption-key-file flag is provided, the architecture wraps the selected transport with NewEncryptedTransport from transport/encrypted.go, which applies AES-256-GCM encryption to all traffic. This encrypted transport can then be further wrapped with CompressedTransport for gzip compression, creating a layered security stack.

What is the difference between proxy mode and raw mode?

Proxy mode (default) operates at the application layer and works on all platforms, tunneling TCP connections through the selected transport. Raw mode (implemented in tunnel/rawsocket_linux.go) operates at the network layer using raw sockets, requires Linux with root privileges, and manipulates packets directly with iptables integration, offering lower-level control but limited platform support.

Can OpenFlux run on iOS devices?

Yes, the OpenFlux architecture supports iOS through the Network Extension framework. The ios-app/ directory contains Swift wrappers that bridge the Go core logic (compiled via Go mobile) to iOS's PacketTunnelProvider. This allows iOS applications to leverage the same transport and tunnel implementations as the desktop version while integrating with the system's VPN architecture.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}