OpenRung

Reach the open internet.

OpenRung is a relay network that helps people living behind internet censorship reach blocked websites and apps through Foundation-operated and volunteer-run relays in unrestricted regions.

Website · Architecture · WSS fallback · Broker API · Report an issue

---

How it works

OpenRung connects censored users with relays in unrestricted regions, similar in spirit to Tor's Snowflake:

• Clients (mobile VPN apps, the desktop proxy app, and a terminal client with proxy and full-device TUN modes) route user traffic through a relay.
• Relay operators — the OpenRung Foundation and community volunteers — run a small command-line app that relays that traffic to the open internet.
• The broker is a control plane only: it matches clients with healthy relays and never proxies user traffic.

flowchart LR
    client["📱 Client app<br/>(VPN mode)"]
    relay["🔁 Relay"]
    broker["🧭 Broker<br/>(control plane)"]
    web["🌐 Open internet"]

    client -. "relay discovery" .-> broker
    relay -. "register + heartbeats" .-> broker
    client == "VLESS + REALITY + Vision" ==> relay
    relay ==> web

Relay transport uses Xray-core's VLESS + REALITY + Vision, designed to be hard to distinguish from ordinary TLS traffic. The broker ranks relay candidates using recent shared metrics — connection success, active sessions, observed latency, and handshake retransmissions — so clients are steered toward relays that actually work.

End-user broker-facing clients share the independently versioned brokerapi Go module. It is the single source for relay directory requests and raw-response signature verification, identity and cache-control headers, telemetry and WSS-ticket requests, the loopback-only cleartext exception, and the broker TLS transport. For the Cloudflare front that transport opportunistically uses a compiled-in ECH configuration, refreshes it from authenticated retry configurations, and quickly retries with ordinary TLS when ECH is blocked. It never bootstraps ECH through DNS and never applies ECH to the CloudFront front. That front omits the TLS server name instead, letting the encrypted HTTP Host header select the distribution while the same certificate verification runs against its exact hostname. On a direct connection the CloudFront front therefore never puts its hostname in a cleartext ClientHello, while the Cloudflare front conceals its own only as long as ECH survives — the ordinary-TLS fallback sends it. A configured proxy tunnels both fronts outside this transport and keeps sending the name.

The desktop app and both mobile clients still try direct Reality first. When a genuine network failure blocks a direct-mode Foundation relay, that relay may advertise its own signed WSS fronts. Each CDN front terminates at the same relay's local sidecar, which carries opaque Reality bytes only to that relay's loopback Reality listener. The broker issues relay- and front-bound authorization tickets but remains outside the user data path. Those clients and the relay-local sidecar share the transport mechanics from the independently versioned wsscore module; ticket authority, origin authentication, deployment policy, telemetry orchestration, and user interfaces remain in their owning applications.

Highlights

• 🙌 Simple volunteering — one line on any Linux VPS, or one CLI plus an Xray binary; IPv6-first with IPv4 and dual-stack options.
• 🕳️ Works behind CGNAT — volunteer-run relays with no inbound port can join through a reverse-tunnel relay hub.
• ⚡ Direct paths when possible — compatible clients and tunneled relays attempt NAT hole punching first, with the relay hub as the fallback.
• 📱 Full-device mobile client — the OpenRung app routes all device traffic in VPN mode (developed in a separate React Native repository).
• 🛡️ Direct-first censorship fallback — the desktop app and both mobile clients can carry the existing end-to-end Reality connection through a relay-owned WSS/CDN front when the direct route is blocked.
• 🧭 Privacy-aware control plane — the broker matchmakes but never carries user traffic.
• 🗄️ Production-friendly broker — optional shared PostgreSQL state for safe restarts and load-balanced deployments.
• 📊 Operational visibility — opt-in colored per-connection logs for relay operators and an opt-in, token-protected telemetry dashboard.

Quick start

Volunteer: run a relay on your VPS

The fastest way to help people reach the open internet is to turn a Linux VPS with a public IPv4 address into a volunteer relay. One command sets everything up (on Debian/Ubuntu it installs Docker for you):

curl -fsSL https://raw.githubusercontent.com/openrung/openrung/main/deploy/relay/volunteer-up.sh | sudo sh

The script pulls the official relay image, runs it with the same hardened container setup the Foundation fleet uses, auto-detects your server's public IP, mints a stable relay identity and a public adjective-noun relay name, registers with the public OpenRung broker, and confirms the relay is actually serving before it declares success. No account or token is needed.

This is the beginning of the README. Read the rest at the original. Read the full README ↗