Luvus 是一个终端内的 AI Agent 任务控制中心（Mission Control），本文教你两种把 AI Agent 跑在远程服务器上、又在本地终端统一控制的方式：用luvus --remote一键 SSH 直连，或用luvus machine保存多台机器、在本地与远程工作区之间随时切换。

为什么需要远程运行 AI Agent

AI Agent（如 Claude Code、Codex、Copilot CLI）跑一轮任务往往要几分钟甚至更久，还消耗大量上下文窗口。把它放到一台算力更强的远程服务器上，你只需要一台轻量设备（笔记本、甚至手机）当客户端——服务器负责计算，你的终端只负责显示。

Luvus 的远程模型很干净：

• 服务器留在远程：工作区、标签页、终端窗格、Agent 进程全部跑在远程机器上；
• 客户端在你手里：本地终端只做显示和输入，剪贴板、提示音、链接打开都发生在本地；
• 断线不中断：关掉终端、网络掉线、合上笔记本，远程服务器和正在跑的 Agent 都继续运行，重新连上即可恢复现场；
• 不开公网端口：全程走你已有的 SSH 连接，不额外配置端口转发。

远程模式下 Luvus 依然保持"任务控制中心"的能力：Mission Control 视图会列出每台机器上每个 Agent 的状态（running / done / blocked）、token 用量、费用和上下文占比。

前置准备：两端安装 Luvus 并验证 SSH

1. 本地和远程都安装 Luvus

本地机器需要 Luvus 作为客户端，远程服务器需要 Luvus 作为服务端，两台机器各执行一次：

curl -fsSL https://luvus.dev/install.sh | sh

2. 验证免密 SSH 登录

远程工作流的前提是能无人值守地连上服务器。先确认普通 SSH 可用：

ssh devbox

然后用 BatchMode 验证密钥登录是否真正免交互（能打印connected即通过）：

ssh -o BatchMode=yes devbox echo connected

再确认远程已装好 Luvus：

ssh devbox luvus --version

💡 建议在~/.ssh/config里配置一个别名（Host devbox/HostName/User/Port/IdentityFile），后面所有命令都会短很多。跳板机（ProxyJump）、密钥代理等仍由 OpenSSH 配置负责，Luvus 不会保存任何密码或私钥。

方式一：--remote 直连，一条命令接管远程 AI Agent

luvus --remote 一条命令直连

在本地终端执行：

luvus --remote devbox

Luvus 会启动你本地的ssh，在devbox上启动（或找到）Luvus 服务器，然后把当前终端附着上去。第一次连接会自动启动远程的default会话；之后每次连接都接到同一个服务器，之前打开的工作区、窗格和 Agent 原样还在。

完整形式（见 src/cli.rs）是luvus [--session <name>] --remote <host> [ssh args]，host 之后的一切参数都会原样透传给ssh。

自定义端口、私钥与跳板机连接

--remote的 host 参数接受 OpenSSH 的全部目标形式，常用组合：

# 指定用户 luvus --remote alice@dev.example.com # 自定义端口 luvus --remote alice@dev.example.com -p 2222 # 指定私钥 luvus --remote alice@dev.example.com -i ~/.ssh/work_ed25519 # 通过跳板机连接内网机器 luvus --remote private-devbox -J bastion.example.com

密码、硬件密钥确认、主机指纹询问仍由ssh本身处理，Luvus 不读取也不存储这些凭据。

命名远程会话：把不同项目隔离开

不带--session时连接的是远程的default会话。想让不同项目互不干扰，把--session放在--remote之前：

luvus --session api --remote devbox luvus --session frontend --remote devbox

会话不需要预先创建，Luvus 会自动启动并在后续同命令中重新附着；切换会话不会停掉之前的会话和它的窗格。也可以用 SSH 直接查看远程会话列表：

ssh devbox luvus session list

安全断开与重连

在远程 TUI 里按Ctrl+Space q可以干净地断开客户端。重新连接就用同一条命令：

luvus --remote devbox

Luvus 会自动加 SSH keepalive，断掉的连接能被检测到而不是卡死，重连也不会产生第二份服务器。⚠️ 注意区分"断开"和"停止"：只有ssh devbox luvus server stop才会结束远程会话及其中的进程，日常离开请只用断开。

方式二：luvus machine 保存多台机器，一键切换工作区

如果你经常同时管理本地项目和好几台远程服务器，machine功能更合适：把 SSH 机器保存成档案，它们会出现在 Workspaces 侧边栏里，和本地工作区平级，点一下就能切换。

luvus machine add 保存第一台 SSH 机器

luvus machine add build --host dev@buildbox --label "Build box"

执行后 Luvus 会先探测 SSH 并检查远程是否有兼容的 Luvus 二进制：

• 远程已有兼容版本 → 直接完成，档案保存；
• 需要安装 → 交互提示是否允许在远程做用户级安装（默认 No）。明确批准时加--install：

luvus machine add build --host dev@buildbox --label "Build box" --install

其他常用选项：--session <name>指定偏好的远程命名会话，--remote-binary <path>固定一个已有的远程二进制路径，--disabled只记录档案而完全不探测（之后再luvus machine enable build启用）。

本地与远程工作区之间快速切换

保存后，正常启动luvus，Workspaces 侧边栏中本地工作区列在Local之下，保存的机器及其远程工作区紧随其后。选中一个远程工作区，整个界面（标签页、窗格、Agent、文件树、DIFF、Mission Control）就切换到那台机器；选中Local下的工作区又立刻回到本地，而远程服务器、它的窗格和 Agent全程继续运行。

几个值得知道的细节：

• 断开 ≠ 停机：右键机器名选Disconnect只暂停本客户端的连接，远程 Agent 不受影响，Connect即恢复；
• 每个本地命名会话有独立的机器档案：在default会话里加的机器，luvus --session work里看不到，需要分别添加。档案默认存在~/.luvus/machines.json，其他命名会话在~/.luvus/sessions/<name>/machines.json；
• 共享 SSH 连接：同一目标的多条 SSH 命令会复用一条 OpenSSH 连接（~/.luvus/ssh下的 ControlMaster），不容易触发 fail2ban 之类的连接限流；
• 临时想在独立终端里挂一台机器，用一次性命令：luvus machine open build --session review。

常用 machine 管理命令

luvus machine list # 列出所有保存的机器 luvus machine show build # 查看某个档案详情 luvus machine status build # 探测远程服务器是否在线 luvus machine sessions build # 列出远程命名会话 luvus machine rename build "Linux builder" luvus machine disable build # 断开但不关远程服务器 luvus machine enable build # 恢复连接 luvus machine remove build # 仅删除本地档案，远程不受影响

管理命令的实现见 src/machine/cli.rs，SSH 探测、共享连接与字节桥的实现见 src/machine/ssh.rs。remove只删本地档案，远程的会话、窗格和 Agent 都还活着——这是刻意的设计。

两种方式怎么选？

远程连接常见问题排查

1. 连上就断开 / 认证失败

先把 Luvus 摘掉，单独测试 SSH：

ssh -v devbox

再用ssh devbox luvus --version对比两端版本；版本不一致时更新较旧的一端再试。

2. 远程提示找不到 luvus 命令

部分远程 shell 的非交互PATH不含用户安装目录。Luvus 在 POSIX 主机上会自动补查~/.local/bin、~/.cargo/bin、~/.nix-profile/bin等常见位置；仍找不到就检查是否装给了正确的远程账号：

ssh devbox 'command -v luvus || ls -l ~/.local/bin/luvus ~/.cargo/bin/luvus'

3. 机器一直显示 connecting / attention

用luvus machine status build做一次有界探测（只探测，不安装不重启）；需要修复兼容性问题时，在本地执行luvus machine enable build并按提示批准安装。

4. 本地缺少 ssh

执行luvus doctor和ssh -V检查，用系统包管理器安装 OpenSSH 客户端即可。

更完整的故障清单见官方文档 Remote Sessions 与 Multiple Machines。

安全模型小结

🔒 无论哪种方式，Luvus 都不新增任何公网监听：远程桥只存在于 SSH 进程内部，服务器端点只对远程操作系统账号可见。OpenSSH 的认证、加密、主机指纹校验、别名和跳板机配置始终是你的权威配置，Luvus 不存储密码、私钥或主机密钥答案。想从手机浏览器访问远程工作区，请用 Luvus Web 的配对流程（默认只读、需可信 TLS 隧道），而不是把本地 socket 暴露出去。

总结

• 快速上手：luvus --remote devbox，一条命令把远程 AI Agent 搬进你眼前的终端；
• 多机管理：luvus machine add <id> --host <ssh-alias>，在侧边栏和本地/远程工作区之间无缝切换，断开不影响远程任务；
• 核心心智模型：计算留在服务器，眼睛留在客户端——断线随时可重连，Agent 从不因为你的终端关闭而停下。

更多命令参考见 CLI 文档 和项目 README。