QuickTUI

This usually means the download was interrupted or corrupted. Try running the installer again. If the problem persists, the release assets may have been updated — wait a few minutes and retry.

You can also verify your network connection and ensure nothing is intercepting HTTPS traffic (e.g. a corporate proxy).

QuickTUI requires tmux 3.2 or later. Install or upgrade it:

macOS:   brew install tmux
Ubuntu:  sudo apt install tmux
CentOS:  sudo yum install tmux

All settings are stored in ~/.config/quicktui/config. The installer writes this file even if you skip background service registration. After editing, restart the service or restart your manual quicktui-server process to apply changes.

# Access token — required, protects your server from unauthorized access
QUICKTUI_TOKEN=your-secret-token

# Listen address and port (default: 0.0.0.0:8022)
# Use 127.0.0.1 to restrict access to localhost only
QUICKTUI_ADDR=0.0.0.0:8022

# TERM value passed to tmux (default: xterm-256color)
# Use xterm-ghostty if your terminal is Ghostty
QUICKTUI_TERM=xterm-256color

# Locale passed to tmux (default: en_US.UTF-8)
QUICKTUI_LANG=en_US.UTF-8

Restart after editing:

launchctl kickstart -k gui/$(id -u)/ai.quicktui   # macOS service
systemctl --user restart quicktui                  # Linux service
~/.local/bin/quicktui-server                       # manual start

The server cannot find your access token. Check that ~/.config/quicktui/config exists and contains a QUICKTUI_TOKEN=... line. If the file is missing, re-run the installer.

First, verify the server is running. If you registered the background service, check it with:

launchctl list | grep quicktui   # macOS
systemctl --user status quicktui  # Linux

If you skipped service registration, start the server again with ~/.local/bin/quicktui-server, or rerun the exact command printed by the installer.

If the server is stopped, check the logs or terminal output for errors. Make sure your firewall allows the configured port from QUICKTUI_ADDR.

The server is running without a locale. Re-run the installer and set the LANG option to match your system, or pass it explicitly:

curl -fsSL https://quicktui.ai/i.sh | sh -s -- --lang en_US.UTF-8

Ghostty sets TERM=xterm-ghostty by default. If you installed QuickTUI while Ghostty was your active terminal, the server may have inherited this value, which tmux requires to be present on the server as well.

Edit ~/.config/quicktui/config and set:

QUICKTUI_TERM=xterm-ghostty

Then restart the service or restart your manual quicktui-server process:

launchctl kickstart -k gui/$(id -u)/ai.quicktui   # macOS service
systemctl --user restart quicktui                  # Linux service
~/.local/bin/quicktui-server                       # manual start

This usually happens when the server cannot find tmux or cannot open a terminal. If you are running as a background service, check the service logs:

tail -f ~/Library/Logs/QuickTUI/stderr.log   # macOS service
journalctl --user -u quicktui -f             # Linux service

If you started quicktui-server manually, inspect the terminal output from that process instead.

Ensure tmux is installed and the TERM environment variable is set. Re-running the installer will detect and configure these automatically.

If QuickTUI is running as a background service:

# macOS
tail -f ~/Library/Logs/QuickTUI/stderr.log

# Linux
journalctl --user -u quicktui -f

If you started quicktui-server manually, view the output in the terminal where you launched it.

Edit ~/.config/quicktui/config and update the QUICKTUI_ADDR line:

QUICKTUI_ADDR=0.0.0.0:9000

Then restart the service or restart your manual quicktui-server process:

launchctl kickstart -k gui/$(id -u)/ai.quicktui   # macOS service
systemctl --user restart quicktui                  # Linux service
~/.local/bin/quicktui-server                       # manual start

You can also set a different address and port at install time. The installer will save the value to QUICKTUI_ADDR for you:

curl -fsSL https://quicktui.ai/i.sh | sh -s -- --addr 127.0.0.1 --port 9000

curl -fsSL https://quicktui.ai/i.sh | sh -s -- --uninstall

This stops the service when possible and removes the binary, config, known launchd/systemd service files, and logs. It also cleans up leftover service files from partial installs where the binary is already gone.

tmux 3.2 or later is required. Check your version with tmux -V.

QuickTUI connects to your existing tmux server. If no sessions exist yet, you can create one directly from the app, or start one on the server with:

tmux new-session -s mysession

Use the New Session button in the app. You only need the server to be running — no existing tmux sessions are required.

The access token is a secret you set during installation. It protects your server from unauthorized access. You can find it in ~/.config/quicktui/config on your server:

cat ~/.config/quicktui/config

Enter this token when prompted on first login in the app or browser.

Yes. You need your server to be reachable from the internet — either via a public IP, a VPN, or a tunnel service such as Tailscale or Cloudflare Tunnel. Make sure the configured port (8022 by default) is accessible and your token is kept secret.

The tmux session you tried to open no longer exists on the server. It may have been closed or the tmux server was restarted. Refresh the session list and select an active session.

Some input methods (IMEs) do not work directly in the terminal view because the candidate selection UI conflicts with terminal input handling. Use the Edit dialog in the shortcut bar instead:

1. Tap the Edit button in the shortcut bar above the keyboard.
2. Type your text using any input method in the dialog box.
3. Tap Send — the text is sent to the terminal at once.