Install

Install the QuickTUI server

The QuickTUI server runs on your own computer and connects the app to your tmux or Herdr sessions, with end-to-end encryption between the two. This page covers installing and upgrading the server, pairing devices, configuration, the command line, and uninstalling.

• Install and upgrade
• Windows (Microsoft Store)
• Pair a device
• Configuration
• Hooks and services added by the installer
• Command reference
• Uninstall

Install and upgrade

Option 1: the app's setup wizard (recommended)

Use this for a Mac or Linux computer you can sign in to over SSH. Everything happens on your phone.

1. Install QuickTUI from the App Store on iPhone or iPad, or install the Android app (Preview). The setup wizard opens on first launch; to add another computer later, tap + on the server list.
2. Choose Connect Over SSH — Enable Enhanced Features (Recommended), then tap Next.
3. Enter your computer's address, port and user name, and sign in with a password or SSH key. Tap Test Connection, and once it succeeds, tap Next.
4. Choose an install source (Global or China; it defaults to your phone's region) and tap Install. The app signs in over SSH, installs the server and pairs automatically.

Your SSH password or key is used only for this installation. The app doesn't save it.

Option 2: manual install

Use this on a Mac or Linux computer without SSH access, or if you'd rather install it yourself. On Windows, use Microsoft Store instead. Run the matching command on your computer:

Global · macOS / Linux

curl -fsSL https://quicktui.ai/q.sh | sh

China mirror · macOS / Linux

curl -fsSL https://dl.quicktui.cn/q.sh | sh

The command downloads the installer for your OS and CPU architecture over HTTPS and runs it. The installer puts the server in place, writes its configuration, adds agent hooks, registers and starts the background service, and finally walks you through pairing (see Pair a device).

If tmux or Herdr is already on your computer, the installer uses it. If neither is, it installs Herdr from Herdr's official source; it never installs tmux. If the Herdr download fails, the installer warns you and still finishes setting up the server. Install Herdr yourself, then run the install command again.

Install sources: Global and China mirror

Both sources serve the same installer and server; the China mirror is faster from mainland China. The mirror only hosts QuickTUI's own files, so Herdr always downloads from its official source.

The server keeps using the source you installed from for automatic updates. To switch, reinstall once with the other source's command. When you upgrade the server from the app, you can also pick the download source for that upgrade.

Reinstall and upgrade

Run the install command again, or run the setup wizard again for the same computer, to reinstall over the existing server:

• The server is replaced with the latest version of the selected channel and the service restarts. If the replacement fails, the previous version is restored.
• Paired devices, the server identity, the QuickTUI Cloud relay binding and your existing settings are all kept, so there's no need to pair again. Only options you pass explicitly (such as --port) overwrite the matching settings.
• Agent hooks are updated to point at the new version.

The server can also upgrade itself:

~/.local/bin/quicktui-server upgrade check
~/.local/bin/quicktui-server upgrade install

Install locations

macOS

Binary: ~/.local/bin/quicktui-server
Config directory: ~/.config/quicktui-server-v2/
Service: LaunchAgent ai.quicktui

Linux (user)

Binary: ~/.local/bin/quicktui-server
Config directory: ~/.config/quicktui-server-v2/
Service: systemd user service quicktui

Linux (root)

Binary: /usr/local/bin/quicktui-server
Config directory: /root/.config/quicktui-server-v2/
Service: systemd system service quicktui

Windows

App: QuickTUI Server from Microsoft Store, run as quicktui-server
Config directory: %USERPROFILE%\.config\quicktui-server-v2\
Service: startup app QuickTUI Server

On macOS and Linux, the installer doesn't change your PATH or shell configuration. If ~/.local/bin isn't on your PATH, run quicktui-server by its full path; the commands on this page use full paths for that reason.

On Linux, running the install command as root installs a system service: it starts at boot, doesn't depend on anyone signing in, and runs as root. A root install and a regular-user install on the same machine are separate instances; don't mix their configuration, service or binary. If they're already mixed, see FAQ Q.14 to fix it.

loginctl enable-linger

sudo loginctl enable-linger "$USER"

sudo loginctl enable-linger <your-username>

export XDG_RUNTIME_DIR=/run/user/$(id -u)
loginctl enable-linger
systemctl --user restart quicktui

loginctl show-user "$USER" --property=Linger

Windows: Microsoft Store

On Windows, install QuickTUI Server from Microsoft Store:

1. Install Herdr. Sessions on Windows run in Herdr, and the Store app doesn't install it:

   powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

2. Get QuickTUI Server from Microsoft Store and install it.
3. Open QuickTUI Server from the Start menu. The first launch starts the server in the background, turns on start at sign-in and opens the pairing guide (see Pair a device).

Open it from the Start menu the first time: running quicktui-server from a terminal doesn't turn on start at sign-in. To stop it starting at sign-in, turn off QuickTUI Server in Task Manager > Startup apps.

Microsoft Store keeps the server up to date, so upgrade install isn't available on Windows. Run commands in PowerShell as quicktui-server <command>, for example quicktui-server pairing welcome. The first time the server listens, Windows may ask whether to allow it through the firewall.

Installed earlier with the PowerShell install script? The first launch of the Store app removes the old scheduled task or startup entry and stops the old server. Paired devices and settings are kept, so there's no need to pair again. If an administrator created the old scheduled task, the app asks you to remove it in an administrator PowerShell with schtasks /Delete /TN QuickTUI /F. Afterwards you can delete the old %LOCALAPPDATA%\QuickTUI\quicktui-server.exe.

Windows and Herdr

The server looks for Herdr in this order: herdr_bin in the config file, the QUICKTUI_HERDR_BIN environment variable, PATH, then Herdr's official install location. To use your own Herdr, set herdr_bin to its full path, then run quicktui-server service restart.

Native Windows and Herdr on ARM64 computers haven't been fully validated yet. If you run into problems, please let us know.

Install command usage

On macOS and Linux, the install script takes a command followed by options:

curl -fsSL https://quicktui.ai/q.sh | sh -s -- <command> [options]

Without a command, it runs install. The current official server is installed by default; no channel option is needed.

Commands

install

Install the server, or reinstall over an existing one

check

Check runtime dependencies without installing anything

prepare

Install missing dependencies only, without the server

uninstall

Remove the background service and agent hooks (see Uninstall); takes no options

help

Show help

Options for install

--channel preview

Install the preview server

--tag <tag>

Install a specific release

--server <absolute path>

Install a server binary from a local file

-y, --yes

Install non-interactively, without the pairing guide

--addr <address>

Listen address: a host, host:port or http(s)://host:port. A bare host listens on port 8022. Default 0.0.0.0:8022. IPv6 needs brackets and a port, e.g. [::1]:9000

--port <port>

Change only the listen port (default 8022). Can't be combined with an --addr that includes a port

--term <value>

Session TERM (default xterm-256color); tmux backend only

--lang <value>

Session LANG (default en_US.UTF-8); tmux backend only

--no-service

Don't register the background service or open the pairing guide. The server, configuration and hooks are still installed

Use only one of --channel, --tag and --server. For example, to install non-interactively and listen on port 9000:

curl -fsSL https://quicktui.ai/q.sh | sh -s -- install -y --port 9000

Options for check and prepare

--server <absolute path>

Check or prepare a specific local server binary. Without it, the installed server is used; if none is installed, the current official server is downloaded and verified temporarily, then removed

Pair a device

Each phone or tablet is paired separately. The setup wizard pairs automatically; after a manual install, or to add another device, follow the steps below.

After a manual install, the installer usually opens the pairing guide right away. It doesn't when you used -y or --no-service, didn't run it in an interactive terminal, or the computer already has paired devices. On Windows, opening QuickTUI Server from the Start menu opens the pairing guide every time. Otherwise, follow these steps yourself.

Step 1: show a pairing QR code on your computer

# macOS / Linux
~/.local/bin/quicktui-server pairing welcome

# Windows (PowerShell)
quicktui-server pairing welcome

Choose where to show the code when the guide asks. A browser is recommended; the terminal works too, but some terminal fonts make the code unreadable. If your phone can't scan a QR code, choose Pairing text: the guide prints one line of text to copy and paste in the app instead.

Step 2: scan it in the app

1. On the server list, tap +.
2. Choose Other ways to connect.
3. Choose Scan a QR Code to Connect a Computer with Enhanced Features, then tap Next.
4. Scan the QR code and confirm to finish pairing.

With pairing text, choose Paste Pairing Text in step 3 instead, paste the whole line and tap Next. Line breaks and extra spaces copied from the terminal are removed automatically.

The QR code contains a one-time pairing code that is valid for 15 minutes and expires as soon as it's used. Until then, anyone who scans it can pair, so don't share or post it. Pairing text carries the same code and follows the same rules.

You can also skip the guide and generate a code directly with pairing qrcode. Options:

• --browser: show the code in your computer's default browser.
• --text: print pairing text, one line to paste in the app under Paste Pairing Text, instead of a QR code. Can't be combined with --browser or --print-code.
• --select-address: put only one address, picked from a numbered list, in the code. Without it, a computer with several network addresses puts up to five of them in the code, in priority order (host name, then Tailscale and WireGuard addresses, then local network addresses, then public and other addresses), and the app uses the first one that connects.
• --public-url <host:port|URL>: put a specific address in the code, such as the public HTTPS address of a tunnel or reverse proxy (see Remote access). Can't be combined with --select-address.
• --print-code: also print the pairing code. Can't be combined with --browser, --select-address or --text.

Run pairing addresses to see the available network addresses.

You can list and revoke paired devices at any time:

# List paired devices
~/.local/bin/quicktui-server pairing devices list

# Revoke a device
~/.local/bin/quicktui-server pairing devices revoke <device-id>

A revoked device can't open new connections right away, and any open connection closes within 5 minutes; it must pair again to reconnect. To remove every device at once, use pairing identity rotate. It replaces the server identity and clears all pairings; stop the service before running it.

Configuration

Settings live in config.toml, a TOML file in the config directory listed under Install locations. On macOS it's also under ~/.config, not ~/Library. Most commands accept --config <path> to use a different file; the server then keeps its other data in that file's directory.

The server reads its configuration only at startup. After editing the file by hand, restart the service to apply it:

~/.local/bin/quicktui-server service restart

Common settings can also be changed with config set, which restarts the service for you:

~/.local/bin/quicktui-server config show
~/.local/bin/quicktui-server config set --addr 0.0.0.0:9000

The running server reads only the config file, not QUICKTUI_* environment variables. Those variables apply only during installation, when the installer writes them into the config file.

Settings

addr

Listen address as host:port. An http(s):// prefix is stripped; the server always listens on plain HTTP, and all traffic after pairing stays inside the end-to-end encrypted tunnelDefault: 0.0.0.0:8022

session_backend

Default session backend: tmux, herdr, luvus or shell. Must be listed in session_backendsDefault: herdr if Herdr is enabled, otherwise the first enabled backend

session_backends

Enabled backends, comma-separated. Detection only adds, never removes. Once you edit it by hand, detection stops; clear session_backend, session_backends and session_backends_auto to turn it back onDefault: Filled in at each start from detected tmux / Herdr

term

Session TERM; falls back to xterm-256color if the terminfo entry is missingDefault: xterm-256color

lang

Session LANG; falls back to C.UTF-8 if the locale is missingDefault: en_US.UTF-8

tmux_socket

Absolute path of the tmux server socket. The default shares your own tmux serverDefault: tmux-<uid>/default under $TMUX_TMPDIR or /tmp

tmux_bin

Absolute path of the tmux executable. If invalid, the server warns and detects it againDefault: Auto-detected

herdr_bin

Path of the Herdr executableDefault: Auto-detected

herdr_client_retention

How long a Herdr client is kept after a terminal is released (Go duration); 0 disables itDefault: 5m

luvus_client_retention

How long a Luvus client is kept after a terminal is released (Go duration); 0 disables itDefault: 5m

luvus_bin

Executable path for the Luvus backendDefault: None

tmux_env_<name>

Sets environment variable <name> (uppercased) in sessions, e.g. tmux_env_editor = "vim"Default: None

tmux_env_unset

Environment variables to remove in sessions, comma-separatedDefault: None

[agent_bins]

Table of per-agent executable paths, e.g. claude = "/abs/path/claude"Default: None

trusted_proxies

Trusted reverse-proxy IPs / CIDRs, comma-separated; forwarded headers are trusted only from theseDefault: Empty

files_enabled

Enables file browsing; usually toggled in the appDefault: false

update_channel

Automatic update channel: server2 or previewDefault: Set at install

update_region

Update download region: global or cnDefault: Derived from the manifest URL

update_manifest_url

Update manifest URL, set by the install sourceDefault: Built in

releases

Release download URL, set by the install sourceDefault: Built in

log_level

Log level: info, debug (adds debug logs) or verbose (adds more detailed logs)Default: info

debug_categories

Log categories that print debug logs, such as ["WS", "TMUX"]; empty or * means all categoriesDefault: All categories

Keys must be lowercase. The session_backends_auto, tmux_bin_auto and herdr_bin_auto entries in the file are maintained by the server; don't edit them. The legacy token key is retired and removed automatically.

Other files in the config directory

pairing_auth.json

Paired devices and pairing credentials

e2e_identity.json

The server's end-to-end encryption identity; replaced by pairing identity rotate

relay.json
relay_registration_identity.json

QuickTUI Cloud relay binding and registration identity

herdr-sids.json
session-sids.json
session-default-cwd.json

Session IDs and the default working directory for new sessions

agent-wizard*.json

Agent launch configuration downloaded from quicktui.ai, with its signed cache

agentbridge2/

Agent status data and each agent's hook on/off setting

*.lock

Lock files used while writing configuration, pairings and identity

Logs: on macOS they're in ~/Library/Logs/QuickTUI/. On Linux, view them with:

# Regular-user install
journalctl --user -u quicktui

# Root install
journalctl -u quicktui

Hooks and services added by the installer

Agent hooks

Hooks in each agent's configuration report events, such as an agent waiting for approval, a finished task or an error, to the server, which uses them for agent notifications (see FAQ Q.41). The installer adds hooks for these agents:

Claude Code

Adds hooks for session start / end, prompt submit, notifications, stop, before / after tool use, permission requests and moreFile changed: ~/.claude/settings.json (in CLAUDE_CONFIG_DIR if set)

Codex

Adds hooks and removes QuickTUI's old entries from the neighboring config.toml. They take effect only after you trust them with /hooks in the Codex CLIFile changed: ~/.codex/hooks.json (or under CODEX_HOME)

Grok

A hook file owned entirely by QuickTUIFile changed: ~/.grok/hooks/ab2.json (or under GROK_HOME)

OpenCode

A plugin file; opencode.json isn't changed. OpenCode may need a restart to load itFile changed: ~/.config/opencode/plugins/agentbridge2.js (or under OPENCODE_CONFIG_DIR)

Every hook runs quicktui-server ab2hook --agent <name>, which records the agent's event and hands it to the server. If a hook fails, it exits silently without affecting the agent. QuickTUI changes only the entries it added and leaves your existing hooks alone.

Each time the installer runs or the server starts, hooks are updated to point at the current server and old-version hooks are cleaned up. To turn them off or back on:

# Turn off and remove hooks for all agents; they won't be added back automatically
~/.local/bin/quicktui-server hooks uninstall

# Turn hooks back on and install them for all agents
~/.local/bin/quicktui-server hooks install

service uninstall also removes hooks but leaves them turned on, so they return on the next install or server start.

Background service

macOS

~/Library/LaunchAgents/ai.quicktui.plist and the launch script ai.quicktui.sh; starts at sign-in and keeps running

Linux (user)

systemd user service ~/.config/systemd/user/quicktui.service, enabled

Linux (root)

systemd system service /etc/systemd/system/quicktui.service, starts at boot

Windows

Startup app QuickTUI Server from the Microsoft Store app, turned on the first time you open it from the Start menu; manage it in Task Manager > Startup apps

Restarting the service doesn't end your tmux sessions. Beyond the above, the installer changes nothing else on your system, including .bashrc, .zshrc and PATH. A Linux user service needs linger enabled to keep running after you sign out; see above.

Command reference

quicktui-server has no global options; each subcommand takes its own. Add -h or --help to any command for help. Commands marked [--config] accept a config file path.

serve

Run the server in the foreground (this is what the background service runs). Options: --config, --debug-addr <address> (temporary listen address), --term, --lang, --tmux-socket, --log-level, --debug-categories

pairing welcome [--config]

Pairing guide

pairing qrcode [--config]

Show a pairing QR code; options under Pair a device

pairing addresses [--config]

List network addresses usable in the QR code

pairing relay --site global|cn [--config] [--replace-relay]

Pair a device through QuickTUI Cloud: run it on the host, enter the code it shows in the app, then approve on the host

pairing devices list [--config]

List paired devices

pairing devices revoke <device-id> [--config]

Revoke a device

pairing identity rotate [--config]

Replace the server identity and clear all pairings; stop the service first

upgrade check [--config]

Check for a new version

upgrade install [--config] [--channel server2|preview]

Upgrade the server and restart the service; --channel switches channels. Not supported on Windows, where Microsoft Store keeps the server up to date

service install

Register the background service; takes the same options as serve and writes them into the config file

service uninstall [--config]

Remove the background service and agent hooks

service restart

Refresh the service definition and restart the service

hooks install [--config]

Turn on and install hooks for all agents

hooks uninstall [--config]

Turn off and remove hooks for all agents

config show [--config]

Show the config file

config set [--config] [--addr] [--term] [--lang] [--tmux-socket]

Change settings and restart the service

config relay delete [--config]

Remove the QuickTUI Cloud relay binding

doctor [--config]

Show how tmux, Herdr and agent executables are found

version

Show the version

installer, ab2hook, ab2ctl and service win-autostart are called internally by the installer, hooks and the Windows startup app; you don't need to run them.

Uninstall

On macOS and Linux, add uninstall to the install command, or have the server remove its service directly:

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

# Or run directly
~/.local/bin/quicktui-server service uninstall

Uninstalling stops and removes the background service and removes agent hooks. The server binary and config directory are kept, including your pairings, so a later reinstall doesn't require pairing again. Uninstalling affects only the current user's installation; root and regular-user installs are uninstalled separately. tmux, Herdr, their sessions and your agents aren't affected.

On Windows, first stop the server and remove agent hooks in PowerShell, then uninstall QuickTUI Server in Settings > Apps > Installed apps. The config directory is kept, including your pairings:

quicktui-server service uninstall

Remove completely

1. Turn off agent hooks:

   # macOS / Linux
   ~/.local/bin/quicktui-server hooks uninstall
   
   # Windows (PowerShell)
   quicktui-server hooks uninstall

2. Uninstall as described above.
3. Delete the binary and config directory:
   • macOS: ~/.local/bin/quicktui-server, ~/.config/quicktui-server-v2/, ~/Library/Logs/QuickTUI/
   • Linux (user): ~/.local/bin/quicktui-server, ~/.config/quicktui-server-v2/
   • Linux (root): /usr/local/bin/quicktui-server, /root/.config/quicktui-server-v2/
   • Windows: %USERPROFILE%\.config\quicktui-server-v2\; also %LOCALAPPDATA%\QuickTUI\ if you installed earlier with the PowerShell install script
4. tmux and Herdr are installed separately; uninstall them yourself if you no longer need them.

Deleting the config directory also clears your pairings, so every device must pair again after a reinstall.