Question 1

tmux is not installed or the version is too old.

Accepted Answer

macOS / Linux: the session backend is tmux 3.2 or later . The installer does not install tmux — install it yourself with your package manager ( brew , apt , yum , dnf , …) and re-run the installer. Optional: set the installer environment variable QUICKTUI_TMUX_BIN , or the TOML key tmux_bin , to an absolute tmux path. Service registration may also write the discovered path into config. Windows: the default backend is qscn , not tmux. The installer installs qscn automatically under %LOCALAPPDATA%\QuickTUI\ .

Question 2

What happens when I re-run the installer?

Accepted Answer

It detects the existing server binary and switches to upgrade mode : stops the service, stages and version-checks the new binary, atomically swaps it into place, and rolls back on failure. Existing config (address, TERM, LANG, session backend, tmux_bin / qscn_bin , and others) is preserved. Binary paths: macOS/Linux ~/.local/bin/quicktui-server ; Windows %LOCALAPPDATA%\QuickTUI\quicktui-server.exe .

Question 3

How do I pair another device?

Accepted Answer

Run quicktui-server pairing qrcode on macOS/Linux, or & "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" pairing qrcode in Windows PowerShell, then scan the short-lived QR from the native app. Add --browser for a pixel QR, --select-address to choose an address, or --debug-addr https://your.domain behind TLS. This CLI flow currently supports new-device pairing for native apps that can scan the QR; it does not provide a supported full-payload export for new Web or Desktop pairing. Pairing registers a device public key and pins the server identity; it does not create or reveal a root token.

Question 4

Can't connect — connection refused.

Accepted Answer

First check the service: # macOS launchctl print gui/$(id -u)/ai.quicktui # Linux systemctl --user status quicktui # Windows (Scheduled Task; if missing, check HKCU Run fallback) schtasks /Query /TN QuickTUI reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v QuickTUI Prefer service restart / service uninstall with the full path under %LOCALAPPDATA%\QuickTUI\ (covers both Windows modes). If you skipped service registration, start quicktui-server with the same config and address. If it is running, ensure firewall/tunnel allows the port from addr .

Question 5

How does QuickTUI authenticate devices?

Accepted Answer

QuickTUI uses device pairing instead of root or browser token login. Each client pins the server identity and proves possession of its private key inside the current E2E handshake with transcript-bound device_pop_v1 . Direct connections carry the client-server E2E tunnel end to end. QuickTUI Relay only forwards opaque encrypted frames. Web stores a non-exportable device key only on HTTPS or loopback origins; remote plain HTTP is refused. Old root-token profiles must pair again. A legacy per-device token may migrate once inside pinned E2E, followed by fresh PoP authentication and deletion of the old token. Use quicktui-server pairing devices list or quicktui-server pairing devices revoke <device_id> to manage devices; on Windows PowerShell use $env:LOCALAPPDATA\QuickTUI\quicktui-server.exe .

Question 6

Can I connect over the internet?

Accepted Answer

Yes. Make the machine reachable via VPN, a reverse proxy with TLS, a tunnel such as Tailscale or Cloudflare Tunnel , or the optional QuickTUI Relay subscription (bind in the app or with quicktui-server config relay set ). The outer listener speaks plain HTTP on 8022 on the machine, while paired business traffic remains inside the client-server E2E tunnel. Do not expose raw port 8022 to the public internet without TLS in front. Point the tunnel or proxy at http://127.0.0.1:8022 and use the public HTTPS hostname in the app without :8022 . Pairing behind TLS: quicktui-server pairing qrcode --debug-addr https://your.domain (macOS/Linux) or & "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" pairing qrcode --debug-addr https://your.domain (Windows). Keep the short-lived pairing QR private.

Agents on your Mac.
You, on your phone.

What you'll use every day.

Toolbar & D-Pad

Input Bar

Command Palette

Switcher

File Browser

Guides

Quick answers.

Install in one line.
Drive from anywhere.

Agents on your Mac.You, on your phone.