服务器上的 Agent，
在 Mac 上回应。

在 Gnista 的设置 ▸ 远程里，点“连接”，从你的 ssh 配置里选一个主机。Gnista 把它的辅助程序复制过去，接入它在那里找到的每个 Agent，并通过你自己的 ssh 保持一条连接。它们的会话会带着机器名显示在刘海里。

• Mac 上装好 Gnista，macOS 15 或更高版本。
• 一台 Linux 服务器（x86_64 或 arm64 都行），或者一台打开了“远程登录”的 Mac。
• 那台机器上，你登录用的那个用户装好了 Agent：Claude Code、Codex、Gemini CLI、OpenCode、Copilot CLI，或者 Gnista 在 Mac 上能接入的任何其他 Agent。
• 那台机器写在你的 ~/.ssh/config 里。最省事的是一把什么都不用你操作的密钥；如果登录要密码、验证码或批准密钥，Gnista 会在 Terminal 里问你一次。

像下面这样一条就够了。你配置里写的，Gnista 全都照用，所以端口、用户、密钥、ProxyJump，以及 Coder、Codespaces 或 DevPod 加进去的主机，都和在 Terminal 里一样有效。

Host devbox
  HostName devbox.example.com
  User dev
  IdentityFile ~/.ssh/id_ed25519

ssh devbox uname -sm

它应该输出 Linux x86_64、Linux aarch64 或 Darwin arm64。如果 ssh 问要不要信任主机密钥，在那里回答一次就行。

1. 打开 Gnista 的设置 ▸ 远程。点“连接”，选择主机（这里是 devbox）。配置里没有的主机：选“其他主机…”，再填上它。
2. Gnista 用 uname 查看系统，把对应系统的辅助程序复制到那边的 ~/.gnista，再核对它传过去后没有变。然后给它找到的每个 Agent 加上 hooks（钩子）。
3. 这台机器的那一行会写明接入了几个，比如“已连接，2 个智能体”。鼠标悬停可以看到它们的名字。
4. 如果那一行显示“需要你登录。”，点“登录”。Terminal 会打开，你登录一次，Gnista 的连接就借这次登录走。
5. 在服务器上开一个会话。它的那一行会出现在刘海里，项目旁边就是服务器名。

• 每个会话一行。本地会话显示应用的位置，这里显示机器名。鼠标悬停，会看到“在 devbox 上（通过 SSH）”。
• 请求进刘海。Agent 一问，刘海就展开显示请求，和本地会话一样。打开设置 ▸ 通用 ▸ 在 Gnista 中回应提示后，就在刘海里回应；Gnista 会把这项设置同步到服务器上。
• 详细信息。标题、最新消息、token 数和费用，对会记录这些的 Agent，在服务器上读出来。
• 对的标签页。点一下，就调出你 Mac 上的那个终端标签页，也就是 Agent 所在的 ssh、mosh 或 Eternal Terminal 连接，并切到它的 tmux 窗格。在 VS Code、Cursor、Windsurf 或 Zed 的远程窗口里，就调出那个窗口；Claude Desktop 经 SSH 开的会话，就打开它的对话。
• 只登录一次。设置、连接和点击共用一条 ssh 连接，所以 Duo 推送或密钥批准只来一次，不会每次都来。
• 断了会自己连回来。掉线、睡眠或换了网络之后，Gnista 会自动重连。这期间那些行都还在，机器那一行显示“暂时无法连接。”

每台机器的 ⋯ 菜单里有一项“连接”设置。大多数服务器用“自动”就行。“不转发”用一条普通的 ssh 命令传送 hooks 的消息，不用转发。“通过我自己的 ssh”让 Gnista 自己不建任何连接：“设置”装一次辅助程序，再给你一行 RemoteForward 写进 ssh 配置，由你自己的 ssh 会话捎带 Agent 的事件。给你们的 IT 团队看：安全与隐私。

从你的每台 Mac 都连接同一台服务器。每台 Mac 在那边各有一个 socket，它们都会显示这台服务器的会话，一个请求谁先回应就算谁的。在一台 Mac 上点“断开连接”，Gnista 仍会留在服务器上给其他 Mac 用。

每次连接建立，Gnista 都会把这些更新到最新：Gnista 更新后换上新的辅助程序，之后新装的 Agent 也补上 hooks。加 hooks 之前，Gnista 会先备份 Agent 的设置，你自己的 hooks 保留不动。

对每台机器，Gnista 在你的 Mac 上开一个 socket，再运行你的 ssh，把它反向转发过去，这样那边的 hooks 就经这条连接和你 Mac 上的 Gnista 通信。简单说就是：

ssh -N -o ControlMaster=yes -R /home/dev/.gnista/sockets/<this Mac>.sock:<a socket on your Mac> -- devbox

如果服务器不转发 socket，Gnista 就改为转发它回环地址上的一个端口，每次连接都必须先给出一个只有你在那边的账户能读到的密码。如果它什么都不转发，辅助程序就用一条普通的 ssh 命令传送 hooks 的消息。

一行上显示的服务器名，取决于事件从哪条连接进来，而不是服务器自己怎么说，所以一台服务器冒充不了另一台。连接断开时，hooks 找不到 Gnista，会立刻返回，Agent 照常在它的终端里问你。

Linux 的辅助程序从 Gnista 在 GitHub 上的公开下载获取，每个 Gnista 版本、每种处理器只下载一次；只有 Gnista 的密钥为这个版本签过名，Gnista 才会用它。Mac 的辅助程序直接来自你的 Gnista，已签名、已公证。

• “ssh 提示：…”这是 ssh 自己最后报的错。用同一个主机跑一遍上面的检查，然后再点一次“连接”。
• “需要你登录。”点“登录”，在 Terminal 里登录。用 1Password 的话，它的提示可能藏在其他窗口后面；鼠标悬停在那一行上，可以看到 ssh 说了什么。
• “暂时无法连接。”鼠标悬停在那一行上，看 ssh 的原话。Gnista 会一直重试，每次等得更久一些。
• “Gnista 可连接 Linux 机器和 Mac；这台是“…”。”这台主机跑的是别的系统，Gnista 接不了。
• “Gnista 无法下载适用于 Linux 的助手。请确认 Mac 已联网，然后重试。”服务器第一次需要这个版本的辅助程序时，你的 Mac 得能访问 github.com。
• “助手在传输途中被改动，因此 Gnista 没有使用它。”再点一次“连接”。
• “已连接，但没有 Gnista 可连接的智能体。”在服务器上，给同一个用户装上一个 Agent。下次连接建立时 Gnista 会接入它；想马上接入，就点“断开连接”再点“连接”。
• “这与已连接的 … 是同一个账户。”你 ssh 配置里的两个名字指向同一个账户。留一个就行。
• 会话没显示。先确认这台机器的那一行显示“已连接”，再开一个新会话；之前就在跑的会话可能还没有 Gnista 的 hooks。
• “已被你的组织关闭。”你的 Mac 受组织管理，RemoteMachinesAllowed 被关掉了。去问你们的 IT 团队。

• 终端通知：Claude Code 自己的通知是终端里的转义序列，所以会经 ssh 传到 iTerm2 等能显示它们的终端。它们只说有事发生，不说是哪台服务器、哪个会话，回应还得回到标签页里。
• tmux 响铃：打开 monitor-bell，再配一个能把响铃变成通知的终端。免费，局限也一样。
• 写个 hook，推送到手机通知服务，比如 ntfy。在哪儿都能收到，但得你自己写、自己维护，回应也还是得回到终端。

• 服务器上有 root 权限的人都能回应你的批准请求，因为他们能访问那个 socket。只连接你信任的服务器。
• 在刘海里回复和套餐额度只适用于你 Mac 上的会话，服务器的那些行没有。
• “断开连接”会从服务器上删掉 Gnista 的 hooks 和 ~/.gnista，除非还有别的 Mac 在用。如果那时连不上服务器，hooks 会留下；没有 Gnista，它们什么也不做。
• 容器或 Kubernetes pod 里的 Agent：见容器里的 Agent。
• 组织可以为自己的 Mac 关掉远程机器：见托管设置。Gnista 发送什么、发到哪里：见隐私。
• 免费试用 7 天，之后 €19 一次买断。更多见 Claude Code、Codex、Gemini CLI 和 OpenCode。