Getting Started

This page sets up one working connection, VLESS inside TLS, from a server with WaterWall installed to a connected phone. It is the app's default chain and the one our server runs on port 18443.

Where this page comes from

The server file is our server's /etc/waterwall/configs/vless-tls.json, with the domain and UUID replaced by placeholders. The app settings are the ones used when we tested this exact file with the app on 3 November 2026, with the server's Let's Encrypt certificate and TLS Server Verification on. The result is at the end of this page.

Before you start

On the server

Run these steps on the server, as root.

1. Make a UUID

VLESS identifies you with a UUID, a random ID that works like a password. Make one and keep it for step 2 and for the app:

cat /proc/sys/kernel/random/uuid

It prints one line in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, made of the digits 0 to 9 and the letters a to f. Treat it as a secret: anyone with it can use your server.

2. Write the configuration file

Save this as /etc/waterwall/configs/vless-tls.json. Replace <SERVER_HOST> with your domain and <UUID> with the UUID from step 1.

{
  "name": "vless-tls",
  "author": "SRP",
  "config-version": 1,
  "core-minimum-version": 0,
  "nodes": [
    {
      "name": "public-in",
      "type": "TcpListener",
      "settings": {
        "address": "0.0.0.0",
        "port": 18443,
        "nodelay": true,
        "initial-idle-timeout-ms": 15000,
        "active-idle-timeout-ms": 300000
      },
      "next": "tls"
    },
    {
      "name": "tls",
      "type": "TlsServer",
      "settings": {
        "cert-file": "/etc/waterwall/fullchain.pem",
        "key-file": "/etc/waterwall/privkey.pem",
        "sni": "<SERVER_HOST>",
        "min-version": "TLSv1.2",
        "max-version": "TLSv1.3",
        "select-alpns": ["http/1.1"],
        "handshake-timeout-ms": 15000
      },
      "next": "vless"
    },
    {
      "name": "vless",
      "type": "VlessServer",
      "settings": {
        "uuid": "<UUID>",
        "connect": true,
        "udp": true,
        "verbose": true
      },
      "next": "outbound"
    },
    {
      "name": "outbound",
      "type": "TcpUdpConnector",
      "settings": {
        "address": "dest_context->address",
        "port": "dest_context->port",
        "nodelay": true
      }
    }
  ]
}

What each part does is explained in the Configuration Reference.

3. Load the file and open the port

Make sure /etc/waterwall/core.json lists the file in configs, as in Installation, step 5:

"configs": [
  "/etc/waterwall/configs/vless-tls.json"
]

Open the port in the firewall, then restart WaterWall:

ufw allow 18443/tcp comment 'WaterWall VLESS TLS'
systemctl restart waterwall.service
ss -ltnp | grep 18443
Check The last command prints a line with :18443 and Waterwall. If it prints nothing, see Troubleshooting.

In the app

4. Create the profile

  1. On the home screen, tap +. A new profile starts as WaterWall VPN with the chain VLESS + TLS and port 443.
  2. Description: a name you like, for example My server.
  3. Server: your domain, <SERVER_HOST>. Use the domain, not the IP address, so that the certificate check matches.
  4. Port: 18443.
  5. SNI (optional): leave it empty. The app then sends the Server field, which is the name on your certificate.
  6. TLS Server Verification: leave it on.
  7. UUID, under AUTHENTICATION: the UUID from step 1.
  8. Leave everything under OPTIONS as it is, and tap Save.

You do not need to open Configuration: the default chain already matches the server file. Each screen is described in the UI & Profile Guide.

5. Connect

  1. Tap the profile to select it, then tap the power button.
  2. The first time, the system asks for permission: iOS asks whether the app may add a VPN configuration, and Android shows a Connection request. Allow it.
  3. The status changes to Connecting… and then Connected, and the profile row shows Ping: followed by the delay through the tunnel in milliseconds.
Check Open any website in a browser. If the status stays at Connecting… or returns to Disconnected, tap the status text to read the log and see Troubleshooting.

Our result

VERIFIED — TESTED SUCCESSFULLY

On 3 November 2026 we connected the current app build to this server file on our production server, with its Let's Encrypt certificate and TLS Server Verification on. For 93 seconds the phone downloaded and uploaded at the same time: 1,309 MB down and 2,131 MB up (113 and 183 Mbit/s on average on our office line), with no errors and no timeouts. The scenario page has the full result.

The Android app connected to the same server file in the same way, on our test phone, and passed two downloads and two uploads at once; see Android.

Next steps