kookoo1sabzy/BaleVPN: > 🟢 **Simplest start — two Android phones.** A peer-to-peer VPN over Bal

🟢 Simplest start — two Android phones. A peer-to-peer VPN over Bale messenger: one phone shares its working internet with the other, with no third-party server, no signup, and no command line. Install the APK on both, sign in with your Bale account in the app, flip one to Server and the other to Client.

→ Android setup guide

A peer-to-peer VPN that tunnels IP traffic over the voice-call infrastructure of Bale, the national Iranian messaging app. One device runs as the server (provides internet); another as the client (consumes it). To Bale's servers the link looks like a long voice call between two contacts.

The point: when one person has a working / uncensored connection and the other doesn't, the second person can route their traffic through the first — without any extra server, account, payment, or signup. Just install the app on two phones (or a laptop on the server side), make sure the two accounts have each other in their contact list, and connect.

There is no commercial relationship with Bale.

⚠️ Privacy & encryption

The LiveKit data channel is encrypted with DTLS, so traffic is opaque to passive observers on the network and to ISP middleboxes. However, Bale's LiveKit server is the SFU/TURN node and has access to the plaintext of the data flowing through the call. That means:

• Bale can see who relays for whom — every tunnel session is a Bale voice call between two accounts, so Bale's call records reveal the social graph (which account uses which relay, when, for how long).
• Bale can see which destinations you connect to (IP and port, plus the hostname embedded in the TLS SNI of any HTTPS request).
• Bale can read the contents of any traffic that isn't itself end-to-end encrypted. If you only browse https:// sites, the payload is opaque to them; if you access plaintext HTTP / DNS / FTP / etc. through the tunnel, they can read it.

Treat this tunnel like a corporate VPN whose operator you don't fully trust — fine for IP-level reachability (uncensoring), not adequate as an anonymity or end-to-end privacy layer. Use TLS at the application level (HTTPS, encrypted DNS, etc.).

📌 Recommendation from the author

Register the Bale account used with this tool on a virtual phone number rather than your primary one, so the call metadata above can't be tied back to your real identity.

Bale accepts non-Iranian numbers — and for those, Bale's verification code is delivered through Telegram, not by SMS. (Iranian SMS gateways often can't reliably deliver to international numbers, so Bale uses Telegram as the OTP channel for them.) Step-by-step:

1. Get a virtual phone number that can receive SMS. Sonetel works well; other reliable options include JMP.chat (with XMPP), MySudo, Hushed, or Twilio if you're comfortable with their dashboard. Avoid free "throwaway" SMS sites — Telegram and Bale block most of them.
2. Register a Telegram account on that number first. Telegram's OTP arrives via SMS, which works on real virtual numbers. Set a username so Bale's OTP message can find you.
3. Register Bale on the same number. Bale detects it's a non-Iranian number, doesn't send SMS, and instead sends the verification code as a Telegram message to your account from there.
4. Enter the code in the BaleVPN app → done.

A few notes:

• You only need Telegram during Bale sign-up. After that, the BaleVPN app talks to Bale directly; Telegram isn't in the loop.
• Keep paying for the virtual number — losing it means losing the Bale account (recovery on a number you don't control is hard).
• The Bale account is tied to that number forever. Pick a number you're willing to keep.
• The same recipe also lets non-Iranian Telegram users sign up for Bale in general, not just for this project.

⚠️ Responsible use

This tool is meant for normal interactive internet use — web browsing, messaging, email, light app usage. Not for video streaming, large downloads, torrents, or other sustained high-bandwidth workloads.

The tunnel rides on Bale's LiveKit infrastructure. Heavy traffic from a "voice call" stands out on Bale's metrics, strains their servers, and makes the project easier to detect and shut down for everyone. Use responsibly — don't ruin it for the next person.

Supported features

The Node application currently runs as server only — for the client side, use the Android app.

Easiest start: Android server + Android client. Two phones, install the APK on both, sign in with your Bale account in the BaleVPN app, flip the toggle. No root, no command line, no firewall rules.

Most efficient: Linux or macOS Node kernel-TUN server + Android client. The kernel does the IP forwarding (TUN device) and the NAT (iptables MASQUERADE on Linux, pf anchor on macOS) — substantially faster than the userspace alternatives. The Android client connects via the standard VpnService for a fully-integrated system VPN.

The Node server's forwarding mode is selectable at startup via --nat-mode kernel|userspace. kernel requires the one-time setup linked above; userspace runs with no privilege. See the Node guide for details.

Detailed guides

Per-platform setup, manuals, and screenshots:

For protocol internals, wire formats, and architecture details: CLAUDE.md.

Architecture

   ┌──────────────────────────────────────────────────────────────┐
   │     Bale signaling WS  ·  wss://next-ws.bale.ai/ws/          │
   │     (call setup, presence, push events)                      │
   └────┬─────────────────────────────────────────────────┬───────┘
        │ signaling                                signaling
        ▼                                                 ▼
 ┌─────────────────┐                            ┌─────────────────┐               ┌──────────┐
 │     client      │                            │     server      │ ── egress ───►│   open   │
 │    (Android)    │                            │  (Android, or   │      NAT      │ internet │
 │                 │                            │   Node any-OS)  │               └──────────┘
 └────────┬────────┘                            └────────┬────────┘
          │                                              │
          │     ── DTLS-encrypted WebRTC data channel ── │
          └──────────────┐                  ┌────────────┘
                         ▼                  ▼
            ┌────────────────────────────────────────┐
            │    LiveKit SFU  ·  livekit.bale.ai     │
            │    (relays the data channel)           │
            └────────────────────────────────────────┘

• Bale signaling WS — call setup and Bale-side push events. Dropped once the call is up; brought back automatically when needed.
• LiveKit SFU — Bale-operated WebRTC server that relays the DTLS-encrypted data channel between client and server. Carries raw IP packets between the two ends.
• Server owns the egress NAT to the open internet. The SFU just relays; it doesn't route to the internet itself.
• Bale operates both the signaling WS and the SFU, so they can see traffic metadata and any payload that isn't itself end-to-end encrypted (see the privacy note above).

Status

Active research / experimentation. APIs and on-disk formats may change without notice.

Disclaimer

This is an independent reverse-engineering research project. There is no commercial relationship with, and no endorsement by, Bale or any of its operators. The code is published for educational purposes — to document how a closed-source messenger's WebRTC voice-call infrastructure can be repurposed as a generic data tunnel, and to make the wire formats and protocols involved legible to other researchers.

You are responsible for how you use this software. The author(s):

• make no warranty of any kind, express or implied, including merchantability, fitness for a particular purpose, security, or compliance with any local law or regulation;
• accept no liability for any damages, claims, costs, or losses arising from use, misuse, or inability to use this software;
• accept no responsibility for any violation of Bale's terms of service, of any applicable telecommunications, privacy, or computer-access laws, or of any third-party rights, that may arise from running this software.

Only use it on accounts and infrastructure you own or have explicit permission to test against. Do not use it to circumvent access controls you have not been authorised to bypass, to evade lawful network policy, or to harm any third party.

If you are unsure whether your intended use is lawful in your jurisdiction, consult a qualified lawyer before proceeding.