Whitelist Bypass

VP8 pacing controls how frequently the joiner sends VP8 frames through the SFU. This is configured on the joiner; the creator automatically adjusts to the values sent by the joiner at the start of the session.

Note: Obfuscation and VP8 pacing only work in headless-headless mode (both creator and joiner must be in headless mode).

• Override VP8 pacing: When enabled, you can set the following:
  • FPS: Nominal VP8 frame rate (Range: 1..240, typically 24-30).
  • Batch: Tick density multiplier. Real sending speed $\approx$ fps \times batch frames/sec (Range: 1..256).

Throughput Calculation: Throughput \approx fps \times batch \times 1126 bytes/frame.

Warning: Higher batch values increase CPU load on the phone and the SFU. If you see packet drops or connection instability in the logs, decrease the batch value.

Whitelist Bypass tunnels internet traffic through video calling platforms (VK Call, Yandex Telemost, WB Stream) to bypass government whitelist censorship. It uses two primary tunnel modes:

1. DC (DataChannel) mode: Uses Pion to open an SCTP DataChannel on the publisher, tunneling TCP/UDP traffic through it. Frames pass through the platform's SFU as standard DataChannel payloads.
2. Video mode: The tunnel rides on a published VP8 video track instead of a DataChannel. This is useful when the SFU rate-limits DataChannels but allows RTP traffic (e.g., Telemost), or when the platform requires a video track (e.g., WB Stream).

The recommended architecture is headless on both ends (using pure Go/Pion to talk directly to the SFU) to enable features like ChaCha20 obfuscation and configurable VP8 pacing. A legacy browser-based path exists for VK DC but is being phased out as it is slower and lacks obfuscation.

The headless-vk-bot is a standalone Go binary that acts as a server-side version of the desktop Creator. It listens to VK Community Long Poll events and, upon receiving a command, launches the appropriate headless-creator to generate a join link. This is ideal for VPS deployment.

Prerequisites

1. VK Community: Create a VK community and obtain a community access token, group ID, and your VK ID.
2. Binaries: Download the following binaries from GitHub Releases and place them in a single directory (e.g., /usr/local/bin/):
   • headless-vk-bot-linux-x64
   • headless-vk-creator-linux-x64
   • headless-telemost-creator-linux-x64
   • headless-wbstream-creator-linux-x64
   • headless-dion-creator-linux-x64 Note: Ensure they are executable: chmod +x /usr/local/bin/headless-*.
3. Cookies: You must provide logged-in session cookies for all four platforms. In the desktop Creator, click Export Cookies to get a cookies.zip containing:
   • cookies-vk.json
   • cookies-yandex.json (for Telemost)
   • cookies-wbstream.json
   • cookies-dion.json Unzip these and move them to your server.

The VK Bot allows you to initiate calls via VKontakte messages without direct access to the Creator. To set it up, you must create a VK community and configure its API permissions.

Setup Steps

1. Create a VK Community: You can use a private community.
2. Enable API Access:
   • Go to Management -> Additional -> Work with API -> Create key.
   • Select all permission checkboxes.
   • Confirm via SMS and copy the generated token.
3. Enable Long Poll API:
   • Go to Long Poll API -> Event Types.
   • Under Messages, select all checkboxes.
4. Enable Bot Capabilities:
   • Go to Messages -> Bot Settings and enable Bot Capabilities.
5. Identify IDs:
   • Community ID: Copy the numeric ID of your community (exclude the club prefix).
   • User IDs: Find your VK ID via Profile -> Manage VK ID -> My Data. To allow multiple users, list IDs separated by commas (e.g., 12345,67890).
6. Configure Creator:
   • In the Creator application, enter the Token, Group ID, and User IDs (comma-separated).
   • Save and enable the bot. The bot will ignore commands from any user not included in the User IDs list.

The Desktop Joiner is a GUI application supporting VK, Telemost, and WB Stream. It can create a system-wide VPN tunnel (TUN) or run as a local SOCKS5 proxy.

Installation: Download the appropriate version from GitHub Releases:

• Windows: .exe (portable)
• Linux: .AppImage
• macOS: .dmg

Running with System VPN (TUN mode):

1. Paste the call link (supports wbstream://, https://stream.wb.ru/..., https://telemost.yandex.ru/j/..., or VK links).
2. Configure optional settings (Name, SOCKS5 host/port, Tunnel mode, VP8, DNS).
3. Ensure SOCKS5 only is unchecked (default). This requires root/admin privileges.
4. Click Start and wait for TUNNEL CONNECTED.

Running as SOCKS5 Proxy only:

• Check the SOCKS5 only box. This does not require root/admin privileges and behaves like the iOS version.

Platform-specific Privileges for TUN mode:

• Windows: Requires Administrator (UAC prompt will appear).
• Linux: Requires root. Run: xhost +SI:localuser:root then sudo -E ./WhitelistBypass\' Joiner-*.AppImage --no-sandbox.
• macOS: Requires root. Run: sudo "/Applications/WhitelistBypass Joiner.app/Contents/MacOS/WhitelistBypass Joiner".

VK Users: The desktop GUI will automatically open a window for VK Captcha solving.

To run the bot as a persistent background service on Linux, create a systemd unit file at /etc/systemd/system/wlb-vk-bot.service.

```ini
[Unit]
Description=Headless VK bot (whitelist-bypass)
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/headless-vk-bot \
  --token <community_access_token> \
  --group-id <community_id> \
  --user-id <vk_id_1>,<vk_id_2> \
  --bins-dir /usr/local/bin \
  --vk-cookies /etc/whitelist-bypass/cookies-vk.json \
  --tm-cookies /etc/whitelist-bypass/cookies-yandex.json \
  --wb-cookies /etc/whitelist-bypass/cookies-wbstream.json \
  --dion-cookies /etc/whitelist-bypass/cookies-dion.json
Restart=always
RestartSec=5
User=wlb

[Install]
WantedBy=multi-user.target

Activation commands:

sudo systemctl daemon-reload
sudo systemctl enable --now wlb-vk-bot
sudo journalctl -u wlb-vk-bot -f

Note: When the service stops, it sends SIGTERM to all running creator processes to ensure sessions are closed properly.

iOS only supports SOCKS5 proxy mode (no system VPN). To proxy all device traffic, you must use a third-party VPN app that supports SOCKS5 (e.g., Happ, Shadowrocket, or Streisand).

1. Install whitelist-bypass-proxy.ipa (unsigned) from GitHub Releases.
2. Install a SOCKS5-compatible VPN app.
3. Open whitelist-bypass, select a tunnel mode (DC or Video), paste the call link, and press Go.
4. Wait for "Tunnel Active". The app will display the SOCKS5 proxy address (e.g., socks5://user:pass@127.0.0.1:1081).
5. Copy the SOCKS5 parameters and enter them into your VPN app.

Using Happ (Recommended):

1. In whitelist-bypass, wait for "Tunnel Active" and tap Copy v2ray URL. This copies a link like socks://...@127.0.0.1:1081#WLB-1081.
2. Open Happ, tap + (top right), and select Import from clipboard.
3. Enable the WLB-1081 server in the list.

Note: Because this avoids NetworkExtension, the SOCKS5 port may change between app launches. If the tunnel stops working after a restart, delete the old server in Happ and re-import the v2ray URL.