turnable

The client allocates a relay address on the platform's TURN server, connects to the Turnable server, and from there it forwards traffic to the configured destination. Simple and stable, but is usually heavily throttled and can be detected.

sequenceDiagram
    participant App as Source
    participant TC as Turnable Client
    participant TURN as TURN Server
    participant TS as Turnable Server
    participant Dest as Destination

    TC->>TURN: Join call, allocate relay endpoint
    Note over TC,TS: Dedicated tunnel established

    loop Traffic
        App->>TC: TCP/UDP data
        TC->>TS: Relay
        TS->>Dest: Forwarded data
        Dest-->>TS: TCP/UDP data
        TS->>TC: Relay
        TC-->>App: Forwarded data
    end

The client allocates a relay address on the platform's TURN server and connects to the destination server directly. Does not require a Turnable server. ⚠️ Not recommended and is dangerous to use.

sequenceDiagram
    participant App as Source
    participant TC as Turnable Client
    participant TURN as TURN Server
    participant Dest as Destination

    TC->>TURN: Join call, allocate relay endpoint
    Note over TC,Dest: Dedicated tunnel established

    loop Traffic
        App->>TC: TCP/UDP data
        TC->>Dest: Forwarded data
        Dest-->>TC: TCP/UDP data
        TC-->>App: Forwarded data
    end

The client and server communicate through the platform's SFU, disguising all traffic as a screencast stream.

sequenceDiagram
    participant App as Source
    participant TC as Turnable Client
    participant SFU as SFU (VK)
    participant TSM as Server - Main Peer
    participant TSD as Server - Dedicated Peer
    participant Dest as Destination

    TC->>SFU: Join call, locate server main peer SSRC by username
    TC->>SFU: SDP response with main peer SSRC + start fake screencast
    TSM-->>TC: ready ack

    TC->>TSM: auth
    TSM-->>TC: auth ack + dedicated peer SSRC

    TC->>SFU: SDP response with dedicated peer SSRC
    TSD->>SFU: SDP response with client peer SSRC
    Note over TC,TSD: Dedicated tunnel established

    loop Traffic
        App->>TC: TCP/UDP data
        TC->>TSD: Relay
        TSD->>Dest: Forwarded data
        Dest-->>TSD: TCP/UDP data
        TSD->>TC: Relay
        TC-->>App: Forwarded data
    end

Turnable provides end-to-end encryption, user and route management for your convenience. You need a VPS with a public IP and an internet connection, on which you are able to open ports freely. Keep in mind that Turnable is just a tunnel - you still need to set up a VPN/Proxy server. It is recommended that you use WireGuard.

1. Generate a key pair

./turnable config keygen
# priv_key=whH/S/GPFJ37zGv8n...
# pub_key=BWEx0ygunbFJFCrIN...

2. Write config.json

{
    "platform_id": "vk.com",
    "call_id": "...",
    "priv_key": "...",
    "pub_key": "...",
    "relay": {
        "enabled": true,
        "proto": "dtls",
        "cloak": "none",
        "public_ip": "...",
        "port": 56000
    },
    "p2p": {
        "enabled": false
    },
    "provider": {
        "type": "json",
        "path": "store.json"
    }
}

3. Write store.json

{
    "routes": [
        {
            "id": "https",
            "address": "127.0.0.1",
            "port": 443,
            "socket": "tcp",
            "transport": "kcp",
            "client_prefs": {
                "username": "Maxim Smirnov  ",
                "type": "relay",
                "encryption": "handshake",
                "name": "My Server",
                "peers": 10
            }
        }
    ],
    "users": [
        {
            "uuid": "...",
            "allowed_routes": ["https"]
        }
    ]
}

[!WARNING] Do not share the user UUID willy-nilly, as it is used for authentication!

4. Start the server

./turnable server

Flags:
  -c, --config string   server config JSON file path (default "config.json")
  -s, --store string    server user/route store JSON file path (default "store.json")
  -V, --verbose         enable verbose debug logging

5. Generate client config

./turnable config generate <route-id> <user-uuid>
# turnable://uuid:call@vk.com/route?pub_key=...

Flags:
  -c, --config string   server config JSON file path (default "config.json")
  -j, --json            output config in json format
  -s, --store string    server user/route store JSON file path (default "store.json")

Produced config URL or JSON is the only thing you need to provide to your users.

Setting up a Turnable client is almost effortless. Keep in mind that Turnable is just a tunnel - you still need to set up a VPN/Proxy client. It is recommended that you use WireGuard. To set it up on Android, follow this guide.

1. Obtain a client config

Ask a Turnable server operator for a client config.

If you would like to, you can directly connect to a remote UDP server if you do not care about stability, fast recovery, muxing, encryption, user management or anything that a Turnable server provides. ⚠️ Not recommended and is dangerous to use.

./turnable config direct <platform-id> <call-id> <username> <gateway-addr> -n [peers]
# turnable://INSECURE-DIRECT-RELAY:call@vk.com/?username=...&type=direct&...

2. Start the client

./turnable client -l 127.0.0.1:1080 [config-url]

Flags:
  -c, --config string    client config JSON file path (default "config.json")
  -l, --listen string    local TCP/UDP listen address (ip:port) (default "127.0.0.1:0")
  -i, --no-interactive   disable interactive mode
  -V, --verbose          enable verbose debug logging

You can either specify a path to the JSON file, or the configuration URL.

3. Point your app at the local address

Configure your proxy/VPN client application to use 127.0.0.1:1080 (or whatever address you chose)