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 QUICKTUI_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 the new binary, sanity-checks --version , atomically swaps it into place, and rolls back on failure. Existing config (token, address, TERM, LANG, session backend, QUICKTUI_TMUX_BIN / QUICKTUI_QSCN_BIN , and others) is preserved. Binary paths: macOS/Linux ~/.local/bin/quicktui-server ; Windows %LOCALAPPDATA%\QuickTUI\quicktui-server.exe .

Question 3

QuickTUI says "token is required".

Accepted Answer

Ensure the config file contains a non-empty token: QUICKTUI_TOKEN=… Default path: ~/.config/quicktui/config (Windows: %USERPROFILE%\.config\quicktui\config ). Or pass --token . Serve uses flag > config file ; a process environment variable alone is not enough for a normal quicktui-server process.

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 --restart-service / --uninstall-service with the full path under %LOCALAPPDATA%\QuickTUI\ (covers both Windows modes). If you skipped service registration, start quicktui-server with the same token and address. If it is running, ensure firewall/tunnel allows the port from QUICKTUI_ADDR .

Question 5

What is the access token?

Accepted Answer

A secret stored as QUICKTUI_TOKEN — it protects the server HTTP API and browser login. You set it during installation (or later with the installer --token / --rotate-token flags). Find it on your machine: cat ~/.config/quicktui/config # or quicktui-server --dump-token On Windows the config is %USERPROFILE%\.config\quicktui\config and the binary is usually %LOCALAPPDATA%\QuickTUI\quicktui-server.exe (use that full path if quicktui-server is not on PATH). Browser client: open http://<host>:8022 and paste the access token once when prompted. Native app pairing: do not paste the access token. On the machine run quicktui-server --pair-qrcode (macOS/Linux) or & "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --pair-qrcode (Windows), optional --browser , then scan in the app. Pairing uses a short-lived pairing code inside the QR, not the access token.

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 --update-config-relay ). QuickTUI speaks plain HTTP on 8022 on the machine. 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 --pair-qrcode --addr https://your.domain (macOS/Linux) or & "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --pair-qrcode --addr https://your.domain (Windows). Keep tokens and pairing codes secret.

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.