电脑里的 Agent,
手机实时操作

# macOS / Linux
curl -fsSL https://herdr.dev/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

完整文档：herdr.dev/docs/install

多数 Linux 发行版可以直接用包管理器安装，macOS 可以用 Homebrew：

# Debian / Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# macOS（Homebrew）
brew install tmux

QuickTUI 需要 tmux 3.2 及以上版本。其他系统见 tmux 安装文档。

tmux 不支持 Windows，Windows 上请使用 Herdr。

安装命令会原地升级已有的服务端：用新版本替换 QuickTUI 服务端并重启服务，替换失败时自动恢复原版本。

已配对的设备、服务端身份和现有配置（端口、会话后端等）都会保留，无需重新配对。

在电脑上运行配对引导：

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

# Linux（以 root 安装）
sudo /usr/local/bin/quicktui-server pairing welcome

# Windows（PowerShell）
quicktui-server pairing welcome

按引导选择显示二维码的方式：推荐在桌面浏览器中显示；也可以直接在终端中显示，但部分终端字体可能导致二维码无法识别。

二维码出现后，在 App 中：

1. 在服务器列表点 +。
2. 选择 其他连接方式。
3. 选择 扫描二维码连接已启用增强功能的电脑，点 下一步。
4. 将摄像头对准二维码，完成配对。

可以。任选一种方式，让手机能访问到你的电脑：

QuickTUI Cloud 中转

无需任何网络配置。每个账号每月有免费中转流量，经常使用可订阅 QuickTUI Cloud。

VPN

例如 Tailscale，手机和电脑处在同一个虚拟网络里即可直连。

隧道或反向代理

例如 Cloudflare Tunnel 或带 TLS 的反向代理，指向 http://127.0.0.1:8022，然后在 App 里填写公网 HTTPS 域名（不带 :8022）。

配对码、设备登录和你的所有操作都在端到端加密隧道里传输，即使直接开放 8022 端口，别人也无法窃听内容或冒充你的电脑。不过直接开放时，外界能看到这里运行着 QuickTUI 及其版本号等少量信息，大量恶意连接也可能让你自己的设备暂时连不上，所以更推荐上面几种方式。

通过隧道或反向代理配对时，先把 QuickTUI 服务端更新到最新版，再生成带公网地址的配对二维码：

# macOS / Linux
~/.local/bin/quicktui-server pairing qrcode --public-url https://your.domain

# Windows（PowerShell）
quicktui-server pairing qrcode --public-url https://your.domain

隧道或反向代理需要保留原始 Host 请求头，并发送 X-Forwarded-Proto；Cloudflare Tunnel 默认两者都满足。如果你的代理不发送该请求头，还需要把 QuickTUI App 更新到最新版。

配对二维码短期有效，请勿泄露。

QuickTUI 通过设备配对来认证，全程端到端加密：

配对时

配对二维码里包含一次性配对码和电脑的身份指纹。配对码 15 分钟内有效、只能用一次，而且只在加密通道里传输。App 会记住电脑的身份，之后只连接身份一致的电脑，别人无法冒充。

设备密钥

每台手机在配对时生成自己的密钥，私钥保存在系统安全存储里（iPhone 的安全隔区或钥匙串，Android 的 Keystore），不会离开手机。

每次连接

App 先核对电脑身份，再用设备私钥证明自己是已配对的设备，双方为这次连接协商出全新的加密密钥。终端、文件、端口转发等所有数据都经过加密，并有防重放保护。

经 QuickTUI Cloud 中转时

中转服务只转发加密后的数据，看不到内容，也无法冒充任何一方。唯一的例外是推送通知：开启后，中转服务在投递时会短暂看到通知文字。

撤销设备

手机丢失或不再使用时，在电脑上撤销它：

# 列出已配对设备
~/.local/bin/quicktui-server pairing devices list

# 撤销指定设备
~/.local/bin/quicktui-server pairing devices revoke <设备 ID>

撤销后，该设备最迟 5 分钟内被断开，之后无法再连接。Windows 请在 PowerShell 中运行同样的命令，以 quicktui-server 开头。

先确认服务端正在运行：

# macOS
launchctl print gui/$(id -u)/ai.quicktui

# Linux
systemctl --user status quicktui

# Linux（以 root 安装）
systemctl status quicktui

# Windows（PowerShell）
Get-Process quicktui-server

没有运行就重启服务：

# macOS / Linux
~/.local/bin/quicktui-server service restart

# Linux（以 root 安装）
sudo systemctl restart quicktui

# Windows（PowerShell）
quicktui-server service restart

服务在运行但仍然被拒绝时，请确认防火墙、VPN 或隧道放行了服务端端口（默认 8022）。

Linux 普通用户安装的服务端以 systemd 用户服务运行，默认随登录会话启停。关闭 SSH 连接或退出登录后，服务端可能随之停止，手机将无法连接。开启 linger 即可常驻运行，根据情况选择对应的命令：

1. 直接开启（本机登录或当前用户有权限时）：

loginctl enable-linger

2. 提示权限不足（如 Access denied、Interactive authentication required，常见于 SSH 远程登录）。有 sudo 权限时：

sudo loginctl enable-linger "$USER"

没有 sudo 权限时，请管理员代为执行：

sudo loginctl enable-linger <你的用户名>

3. 提示 Failed to connect to bus。如果是用 su 或 sudo -u 切换到该用户后运行的，当前会话缺少用户总线，请改为直接以该用户 SSH 登录后再运行；或先补上运行时目录再开启：

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

如果系统本身没有以 systemd 启动（部分容器、未启用 systemd 的 WSL），用户服务和 linger 都无法使用，请改用 root 安装，或先为系统启用 systemd。

确认已开启：输出 Linger=yes 即可。

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

开启后服务端会开机自启并常驻运行，与是否登录无关。以 root 安装的系统服务不受此影响。