q quicktuiv1
iOS AppiOS → Android AppAndroid →

Guide · Remote access

Reach your QuickTUI server from anywhere

Connect to the QuickTUI server on your computer when your phone isn't on the same network: through Cloudflare Tunnel, your own HTTPS reverse proxy, or a port forward on your router. This guide covers what each setup needs and how to pair through it.

Try the simpler options first. QuickTUI Relay needs no network setup at all and works well in mainland China. Tailscale lets your phone reach your computer over a private network without opening any port, though it can be slow in mainland China unless you run your own DERP relay. See Can I connect over the internet? The setups below suit people who already run a domain, a reverse proxy or a public IP.

Before you start

The server speaks plain HTTP
The QuickTUI server listens on 0.0.0.0:8022 by default and needs no TLS certificate of its own. Pairing codes, device sign-in and everything you do travel inside an end-to-end encrypted tunnel, and the app checks your computer's identity fingerprint on every connection. Even an http:// address can't be read or impersonated.
What the app reaches
The app needs one base address, http://host:port or https://host[:port]. Through it, it requests /.well-known/quicktui-server-capability and opens a WebSocket at /e2e.
No sub-paths
The server must own a whole hostname (or port). An address such as https://example.com/quicktui/ isn't supported; forward every path from the root to the server.
Changing the address doesn't need re-pairing
Pair once on your local network, then open the server's Edit Server page in the app and change scheme, host and port to the remote address. The app keeps the same pairing and verifies the identity fingerprint.
Pairing through a public address
To pair directly through a tunnel or proxy, put its public address in the QR code with --public-url: 
# macOS / Linux
~/.local/bin/quicktui-server pairing qrcode --browser --public-url https://qt.example.com

# Windows (PowerShell)
quicktui-server pairing qrcode --browser --public-url https://qt.example.com
Then scan it in the app as described in Pair a device. --public-url works the same with --text, which prints pairing text to paste in the app instead of a QR code.
Trusted proxies
The server limits how many handshakes each source address can start, so a flood of junk connections can't lock you out. Behind a tunnel or proxy, every connection appears to come from the proxy and shares one allowance. Set trusted_proxies to the proxy's own address so the server counts the real client address from X-Forwarded-For (see Set trusted proxies). List only proxy addresses, never client networks.

Cloudflare Tunnel

Cloudflare Tunnel connects your computer out to Cloudflare, and you reach it through a hostname on your domain over HTTPS. You need no public IP and no router changes. Your domain must be on Cloudflare.

  1. In the Cloudflare dashboard, open Zero Trust → Networks → Tunnels, create a tunnel and follow the steps to install and run cloudflared on your computer.
  2. Add a Public Hostname to the tunnel: hostname qt.example.com, type HTTP, URL localhost:8022.
  3. Set trusted proxies to 127.0.0.1,::1 (see Set trusted proxies).
  4. In the app, use https://qt.example.com, without :8022. For a server you've already paired, set scheme to HTTPS, host to qt.example.com and port to 443. To pair a new device, generate the QR code with --public-url https://qt.example.com.

If you manage the tunnel with a local config file, the ingress rule looks like this:

tunnel: <TUNNEL-UUID>
credentials-file: /home/you/.cloudflared/<TUNNEL-UUID>.json
ingress:
  - hostname: qt.example.com
    service: http://127.0.0.1:8022
  - service: http_status:404

Cloudflare Tunnel supports WebSockets, keeps the original Host header and sends X-Forwarded-Proto by default, so no extra settings are needed.

Don't put Cloudflare Access in front of this hostname. An Access policy that asks for a browser sign-in blocks the app, because the app can't complete that sign-in.

Your own HTTPS reverse proxy

If you already run nginx, Caddy or another reverse proxy, point a hostname at the QuickTUI server. The proxy can run on the same computer or on another machine that can reach port 8022.

The proxy must:

  1. Forward every path on its own hostname (or port) to the server. Sub-paths aren't supported.
  2. Support WebSocket upgrades.
  3. Keep the original Host header.
  4. Send X-Forwarded-Proto: https.
  5. Use a certificate iPhone trusts, such as one from Let's Encrypt.
  6. Allow long idle connections and turn off response buffering. The app sends a heartbeat every 10 seconds; an idle timeout of an hour is a comfortable setting.

Caddy gets a certificate automatically and meets all of these by default:

qt.example.com {
    reverse_proxy 127.0.0.1:8022
}

nginx:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    server_name qt.example.com;

    ssl_certificate     /etc/letsencrypt/live/qt.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/qt.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8022;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 1h;
        proxy_send_timeout 1h;
        proxy_buffering off;
    }
}

When the proxy runs on another machine, replace 127.0.0.1:8022 with your computer's address, such as 192.168.1.10:8022, and use that machine's IP in trusted_proxies. If the proxy listens on a port other than 443, include it in the address, for example --public-url https://qt.example.com:8443.

When the app can't read the server's capability, it shows the HTTP status code. A 404 usually means not every path reaches the server; a 502 usually means the proxy can't reach the server.

Port forwarding on your router

If your home connection has a public IP, you can forward a port on your router to port 8022 on your computer.

This exposes the server directly to the internet. Your traffic stays end-to-end encrypted and no one can impersonate your computer, but anyone can see that a QuickTUI server is running and which version, and a flood of junk connections could keep your own devices from getting through. Prefer one of the options above when you can.

  1. Check that you have a public IP. Compare the WAN IP shown on your router's admin page with the output of curl -4 ifconfig.me on your computer. If they differ, or the WAN IP is in 100.64.0.0/10, you're behind carrier-grade NAT and port forwarding won't work.
  2. Give your computer a fixed local IP with a DHCP reservation on the router, for example 192.168.1.10.
  3. Add a forwarding rule: an uncommon external port such as 28022, to 192.168.1.10 port 8022, TCP.
  4. Set up dynamic DNS on the router, since home IPs change. You get a stable name such as home.example.com.
  5. Use it in the app: on Edit Server, set scheme to HTTP, host to home.example.com and port to 28022. To pair a new device, use --public-url http://home.example.com:28022.

Your computer's firewall must allow incoming connections on port 8022. Some routers can't reach their own public address from inside the home network (no NAT loopback); if the address works away from home but not at home, switch to the local address while at home, or bind QuickTUI Relay and use auto mode.

Set trusted proxies

Needed for Cloudflare Tunnel and reverse proxies, not for port forwarding.

  1. Open the config file in a text editor (other locations are listed under Install locations): 
    nano ~/.config/quicktui-server-v2/config.toml
  2. Add a line with the proxy's address. For cloudflared or a proxy on the same computer: 
    trusted_proxies = "127.0.0.1,::1"
  3. Save, then restart the server: 
    ~/.local/bin/quicktui-server service restart

Optional: accept connections only from the proxy

By default the server also accepts connections from your local network. When a tunnel or proxy on the same computer is your only way in, you can make the server listen on the local machine only:

~/.local/bin/quicktui-server config set --addr 127.0.0.1:8022

After this, devices on your local network can't connect directly, and the app's SSH setup wizard can't pair automatically. Leave the default 0.0.0.0:8022 if you're not sure.

Related