# ReVoltVPN — Server Deployment Guide v7.0 (XHTTP + Reality + Domain-Free) > **Last verified:** 2026-08-02 against live Xray docs at `https://xtls.github.io/en/` > **Transport:** XHTTP (H2 stream-up) + Reality — NOT TCP, NOT XTLS-Vision > **Spoof target:** `www.github.com` (single site, Cloudflare-backed) > **Client:** Domain-free — API routed through tunnel, no domain in APK. See `DOCUMENTATION-ARCHITECTURE-V2.md`. --- ## Connection Flow — End to End ### Step 0: Bootstrap (V2 — domain-free) Before the normal session flow, the app connects with a hardcoded Reality config bundled in the APK (`bootstrapVlessUrl`). This bootstrap client is permanently defined in `xray_config_reality.json` with `email: "bootstrap"`. Xray routing restricts it to `10.254.254.0/24` — only the internal API, zero internet access. ``` App → bootstrap tunnel (Reality, github.com SNI) → polls 10.254.254.1:5000 ↓ Xray "api" outbound (redirect: 127.0.0.1:5000) ↓ Flask Hivemind ``` The app fetches the real per-session VLESS URL through the bootstrap tunnel, disconnects, then reconnects with the real config. From now on, ALL API calls (health, sync, stop) go through `10.254.254.1:5000` inside the tunnel. **Phone never makes a connection to any domain.** ### Step 1: Client taps Connect ``` App → AdMob SSV → server creates VLESS UUID → app bootstraps → polls inside tunnel ### Step 2: Server returns session config The `/session/status` response (from `hivemind/api.py`): ```json { "active": true, "vless_uuid": "550e8400-e29b-41d4-a716-446655440000", "vless_ip": "204.168.246.88", "vless_port": 8443, "reality_pbk": "fHyNQm1UbaFD3wRQn4AAx5SdVzDCzlxm8G4xprpWymI=", "reality_sid": "abc123", "reality_sni": "www.github.com", "reality_fp": "chrome", "xhttp_path": "/revolt", "expires_in_seconds": 3540, "nonce": "1234567890-1716480000", "is_throttled": false } ``` Every Reality parameter comes from the server — client has no hardcoded SNI or path. ### Step 3: Client builds VLESS URL From these response fields, `hivemind_service.dart` builds: ``` vless://550e8400-e29b-41d4-a716-446655440000@204.168.246.88:8443 ?security=reality &type=xhttp &path=%2Frevolt &pbk=fHyNQm1UbaFD3wRQn4AAx5SdVzDCzlxm8G4xprpWymI%3D &sni=www.github.com &sid=abc123 &fp=chrome #ReVoltVPN ``` **Every parameter verified against live docs:** | Parameter | Live doc source | Required? | Value | |-----------|----------------|-----------|-------| | `security=reality` | Reality docs: *"REALITY can only be used together with RAW, XHTTP, and gRPC"* | Yes | `reality` | | `type=xhttp` | XHTTP docs: transport name | Yes | `xhttp` | | `path=/revolt` | XHTTP docs: *"只需填 path，其它不填即可"* | Yes | server-defined | | `pbk=...` | Reality docs: *"password: string — Required. The public key corresponding to the server private key."* | Yes | from `xray x25519` | | `sni=...` | Reality docs: *"serverName: string — One of the server-side serverNames."* | Yes | from `REALITY_SNI_POOL` | | `sid=...` | Reality docs: *"shortId: string — One of the server-side shortIds."* | Yes | `abc123` | | `fp=chrome` | Reality docs: *"fingerprint: string — One of chrome, firefox, safari, random..."* | Yes | `chrome` | | `host=` | XHTTP docs: *"建议没事别设"* (don't set unless needed) | No | intentionally omitted | | `flow=` | VLESS docs: *"XTLS only available: TCP+TLS/REALITY"* (NOT XHTTP) | No | intentionally omitted | ### Step 4: flutter_vless generates Xray client config `flutter_vless` 1.1.4 parses the VLESS URL and produces the equivalent of: ```json { "outbounds": [{ "protocol": "vless", "settings": { "vnext": [{ "address": "204.168.246.88", "port": 8443, "users": [{ "id": "550e8400-e29b-41d4-a716-446655440000", "encryption": "none", "flow": "" }] }] }, "streamSettings": { "network": "xhttp", "security": "reality", "xhttpSettings": { "path": "/revolt" }, "realitySettings": { "serverName": "www.github.com", "fingerprint": "chrome", "publicKey": "fHyNQm1UbaFD3wRQn4AAx5SdVzDCzlxm8G4xprpWymI=", "shortId": "abc123", "spiderX": "" } } }] } ``` ### Step 5: TLS handshake (Reality) ``` Client Server (Xray) | | |── ClientHello ────────────────────→| | SNI: www.github.com | | ALPN: h2 (H2 default w/ Reality) | | random session ID | | | |←── ServerHello ────────────────────| | Certificate: github.com's REAL | | cert (fetched from | | www.github.com:443 by Xray) | | Signed with Reality privateKey | | | |── auth: pbk + shortId ───────────→| | (embedded in TLS extension) | | | |←── TLS 1.3 handshake complete ────| ``` To any DPI box, this looks exactly like a browser connecting to GitHub. ### Step 6: HTTP/2 + VLESS inside the TLS tunnel ``` Inside the TLS tunnel: ┌─────────────────────────────────┐ │ HTTP/2 connection │ │ :method: POST │ │ :path: /revolt │ ← XHTTP path matching │ :authority: www.github.com │ ← Host header (SNI fallback) │ │ │ ┌───────────────────────────┐ │ │ │ VLESS payload │ │ │ │ UUID auth: ✓ │ │ │ │ Actual VPN traffic │ │ │ └───────────────────────────┘ │ └─────────────────────────────────┘ ``` ### Step 7: Xray routes traffic ``` Phone → Xray Reality (8443) │ ├─ dest: 10.254.254.0/24 → api outbound (redirect → Flask 127.0.0.1:5000) ├─ user: bootstrap, other dest → block (blackhole) ├─ port: 25,465,587 → block (SMTP) ├─ port: 135-139,445 → block (NetBIOS) ├─ port: 1900 → block (SSDP) └─ default → direct (freedom → internet) ``` --- ## Will it work? — Answer **Yes, if these 5 things are true on the server:** 1. ✅ `xray_config_reality.json` deployed to `/usr/local/etc/xray/config.json` with the real private key 2. ✅ `hivemind/config.py` has the matching public key in `REALITY_PUBLIC_KEY` 3. ✅ Bootstrap UUID generated (`xray uuid`) and placed in BOTH `xray_config_reality.json` AND `app_config.dart` 4. ✅ Xray restarted after config deploy 5. ✅ Firewall allows inbound 8443 (and 8444 for throttled) **The config is internally consistent.** Every parameter flows from a single source: - `config.py` → API → client → `flutter_vless` → Xray client config - `config.json` → Xray server inbound If those match (and they do in this repo), the tunnel will establish. --- ## Server Setup (clean deploy) ### 1. Install Xray ```bash bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install ``` ### 2. Generate Reality keypair ```bash xray x25519 # Output: # Private key: <44-char base64> ← goes in xray_config_reality.json # Public key: <44-char base64> ← goes in hivemind/config.py ``` ### 3. Generate bootstrap UUID ```bash xray uuid # Output: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 ``` Put this UUID in TWO places: 1. `xray_config_reality.json` — replace `BOOTSTRAP-UUID-REPLACE-ME` in the bootstrap client's `"id"` field 2. `lib/logic/app_config.dart` — replace `BOOTSTRAP-UUID-GOES-HERE` in `bootstrapUuid` ### 4. Deploy Xray config Copy `xray_config_reality.json` from this repo → `/usr/local/etc/xray/config.json` on the server. Replace the private key with the one you just generated: ```json "privateKey": "YOUR_GENERATED_PRIVATE_KEY" ``` ```bash chmod 600 /usr/local/etc/xray/config.json systemctl restart xray systemctl status xray # verify: active (running) ``` ### 5. Verify Xray is listening ```bash ss -tlnp | grep -E '8443|8444' # Should show: # LISTEN 0.0.0.0:8443 (Xray — full speed) # LISTEN 0.0.0.0:8444 (Xray — throttled) ``` ### 6. Verify the spoof cert is reachable ```bash xray tls ping www.github.com:443 # Should show: certificate size > 3500 bytes (good for Reality) ``` ### 7. Deploy Python Hivemind Upload to `/root/`: ``` server_hivemind_5_0.py ← entry point hivemind/ ← package (8 files) ├── config.py ← EDIT: public key, server IP ├── sessions.py ├── xray.py ├── admob.py ├── management.py ├── api.py ├── main.py └── __init__.py ``` ### 8. Edit hivemind/config.py ```python REALITY_PUBLIC_KEY = "YOUR_GENERATED_PUBLIC_KEY" # from xray x25519 VLESS_SERVER_IP = "YOUR_SERVER_IP" # Hetzner/VPS IP REALITY_SNI_POOL = ["www.github.com"] # spoof target VLESS_XHTTP_PATH = "/revolt" # must match config.json ``` ### 9. Install Python dependencies ```bash pip install flask requests ``` ### 10. Create systemd unit `/etc/systemd/system/hivemind.service`: ```ini [Unit] Description=ReVoltVPN Hivemind After=network.target xray.service [Service] Type=simple User=root WorkingDirectory=/root ExecStart=/usr/bin/python3 -m gunicorn -w 1 -b 127.0.0.1:5000 hivemind.main:app Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` ```bash systemctl daemon-reload systemctl enable --now hivemind systemctl status hivemind ``` ### 11. Firewall ```bash # Only open what's needed ufw allow 443/tcp # nginx HTTPS (API) ufw allow 8443/tcp # Xray Reality (full speed) ufw allow 8444/tcp # Xray Reality (throttled) ufw allow 80/tcp # certbot HTTP challenge ufw enable # Keep these internal-only # 5000 — Flask (localhost only, via nginx) # 10085 — Xray API (localhost only) ``` ### 12. nginx (AdMob SSV + website) nginx now serves only two purposes — the app itself never connects to it: - AdMob SSV callbacks (`/api/admob/callback`) — Google → your server, not phone → server - Branding website at the root — user's browser, manually Xray handles all app-to-server traffic through the Reality tunnel. `/etc/nginx/sites-available/revolt`: ```nginx server { listen 443 ssl http2; server_name YOUR_DOMAIN; ssl_certificate /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem; location /api/ { proxy_pass http://127.0.0.1:5000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location / { root /var/www/revolt; index index.html; } } server { listen 80; server_name YOUR_DOMAIN; return 301 https://$host$request_uri; } ``` ### 13. certbot (Let's Encrypt) ```bash apt install certbot python3-certbot-nginx certbot --nginx -d YOUR_DOMAIN ``` --- ## Smoke Test ### From the server: ```bash # 1. Is Xray running? systemctl status xray # 2. Is Hivemind running? systemctl status hivemind # 3. Can Hivemind reach Xray API? curl http://127.0.0.1:10085/stats/query -d '{"pattern":"","reset":false}' # 4. Is Flask alive internally? curl http://127.0.0.1:5000/api/health # → {"ok": true} # 5. Does the API route through Xray work? (simulate tunnel → 10.254.254.1 → Flask) curl http://10.254.254.1:5000/api/health # → should fail (only reachable through Xray tunnel, not directly) # 6. Does the spoof target work? xray tls ping www.github.com:443 ``` ### From a client (after building the Flutter app): The app no longer hits any domain. All API calls go through the tunnel. Verify by building and running the app in debug mode (`ADMOB_BYPASS=True`). ```bash # 7. Tap Connect → app bootstraps → polls inside tunnel → reconnects → timer starts # 8. Health dot turns green (API reachable through tunnel) # 9. Session timer syncs (5 second countdown updates) # 10. Tap Disconnect → timer stops → cleanup POST goes through tunnel → tunnel drops ``` ### Full integration test: ``` 11. Trigger 4 GB → timer shows port-swap → reconnects through bootstrap → speed reduced 12. Support ad top-up → +30 min +2 GB → timer updates without reconnect 13. Kill app while connected → reopen → timer resumes (startup restoration) ``` --- ## Troubleshooting | Symptom | Check | |---------|-------| | App says "Connecting..." forever | Server firewall blocking 8443? `ufw status` | | App connects but no internet | Xray routing broken? Check `journalctl -u xray -f` | | `/session/status` returns 500 | Hivemind crashed? `systemctl status hivemind` | | `xray tls ping` fails | Server can't reach GitHub? DNS? IPv6? | | Stats show 0 bytes | Users missing `email` field? Check `xray.py:add_client()` | | Tunnel starts but immediately dies | `providerBundleIdentifier` mismatch? Must be `com.paladinvpn.app` | | "Session not activated" in app | ADMOB_BYPASS not True? Or SSV callback not firing | | App stuck on "Establishing secure channel…" | Bootstrap UUID mismatch between APK and xray_config? | | Health dot gray after tunnel connects | `api` outbound not working? Check Xray routing rules | | Bootstrap tunnel starts but no config | Hivemind not running on 127.0.0.1:5000? `systemctl status hivemind` | --- ## Changing the spoof target If you ever want to switch from GitHub to another site: 1. Edit `REALITY_SNI_POOL` in `hivemind/config.py` 2. Edit `serverNames` in **both** inbounds in `config.json` (add site + root domain) 3. Update `dest` in `config.json` to the new target 4. Verify: `xray tls ping NEW_TARGET:443` — cert must be > 3500 bytes 5. `systemctl restart xray` --- ## Differences from old TCP/Vision setup | What | Old (SERVER_SETUP.md) | New (this doc) | |------|----------------------|----------------| | Transport | `tcp` | `xhttp` | | Flow | `xtls-rprx-vision` | (none — XTLS doesn't work with XHTTP) | | Spoof target | `www.microsoft.com` | `www.github.com` | | Path | (none — TCP) | `/revolt` (XHTTP path) | | Rate limiting | `uplinkOnly: 187500` (wrong) | `uplinkOnly: 2` (correct seconds), real cap via `tc` | | shortIds | 3 entries | 1 entry matching `REALITY_SHORT_ID` | | Fallback limits | Not present | Intentionally omitted (fingerprint risk per live docs) | | `xhttp_path` in API | Not present | Server sends path, client reads it | | `providerBundleIdentifier` | `com.revoltvpn.app` | `com.paladinvpn.app` | | API transport | HTTPS to domain | Tunnel-internal to `10.254.254.1:5000` | | Domain in APK | `getrevolt.app` | **None** — zero domain strings | | Bootstrap | None (external API polling) | Hardcoded Reality config, tunnel-only API fetch | | Xray outbounds | `direct` + `block` | `direct` + `block` + `api` (redirect → Flask) |