# 连接远程 Runtime Host [English](./runtime-host-remote-access.md) Maka Desktop、TUI 和 CLI 可以通过 TLS、SSH 或明确启用的明文 WebSocket 连接 Runtime Host。CLI 和 TUI 还支持下文所述的实验性 direct peer transport。 ## 设置 Linux 或 macOS Host 在具备 Node.js 22.19 或更新版本的机器上，发布版 CLI 可以用一个命令安装并验证持久 Runtime Host。Linux 使用 systemd user service；macOS 使用 LaunchAgent，并要求该用户存在活跃的 GUI 登录会话： ```sh npx --yes --package maka-agent@latest maka runtime-host setup \ --principal my-desktop \ --preset desktop-client \ --root "$HOME/.maka/runtime-host" \ --project-root "projects=$HOME/Projects" ``` `--principal` 应使用稳定标识；重复执行会替换该 Client 的 credential，不会不断累积 credential。命令会把当前精确版本的 Maka 安装到托管目录，启动仅监听 loopback 的服务，验证新 credential，然后只显示一次连接信息。TUI 或 CLI 使用 `terminal-client`。 在 Host 上运行 `npx --yes --package maka-agent@latest maka runtime-host service uninstall` 会删除 service 与托管 package，但保留 State Root 和 Project 数据。 ## 手动设置 Host 在远程机器构建 Maka，选择持久的 State Root，并注册允许 remote Client 使用的 Project： ```sh npm run build npm --workspace maka-agent exec -- maka runtime-host project add /srv/projects/example --root /srv/maka npm --workspace maka-agent exec -- maka runtime-host project list --root /srv/maka ``` Desktop 目录选择器默认发布运行服务的用户主目录。如需改为明确的目录 allowlist，可在启动服务时传入一个或多个命名根目录： ```sh npm --workspace maka-agent exec -- maka runtime-host serve \ --root /srv/maka \ --project-root projects=/srv/projects \ --project-root data=/mnt/data \ --websocket-port 7443 ``` 只要提供了 `--project-root =`，远程目录浏览就只会显示这些根目录。该参数最多可重复八次。Maka 会在启动时解析每个根目录，并确保浏览和注册始终限制在当前选择的根目录内。 Project path 始终留在 Host。为每个 Client 签发 credential： ```sh npm --workspace maka-agent exec -- maka runtime-host access issue \ --root /srv/maka \ --principal my-desktop \ --preset desktop-client ``` TUI 或 CLI 使用 `terminal-client`。命令只显示 credential 一次。 在 Linux 或 macOS 上，持久安装的 CLI 可以让 loopback Host 在 SSH 会话结束后继续运行： ```sh maka runtime-host service install \ --root /srv/maka \ --project-root projects=/srv/projects maka runtime-host service status --json ``` 安装命令会持久保存当前精确的 Node 与 Maka CLI 路径。重复执行会更新同一个 OS-managed service；未指定 WebSocket port 时会保留现有端口。卸载 npm 包前，应先执行 `maka runtime-host service uninstall`。卸载 service 会保留 State Root 与 Project 数据。Linux 要求启用 systemd user lingering，macOS 要求存在活跃的 GUI 登录会话；条件不满足时安装会给出 可操作的错误，不会声称服务能够持久运行。Service 必须从持久的全局 Maka 安装中安装，不能使用 `npx`。替换操作只会在新的 Runtime Host ready 之后提交；失败时会恢复之前的 service。 ## 选择连接方式 ### 实验性 direct peer 发布版 CLI 与 Desktop 已包含 direct peer native transport，Host 无需安装 Rust 或保留源码。对于通过 SSH 管理的 Host，可以在 Desktop 的电脑管理界面启用；Desktop 会创建独立的实验性 profile，不删除原 SSH profile。同一个 State Root 同时只能启用一个 profile。 等价的 CLI 流程使用 setup 输出的精确 service target： ```sh maka runtime-host service peer enable \ --expected-service-id '' \ --expected-root-path '' \ --expected-root-id '' maka runtime-host service peer descriptor \ --expected-service-id '' \ --expected-root-path '' \ --expected-root-id '' ``` Descriptor 只包含 PeerId、Root ID 和候选 route，不包含 access credential。使用这些值执行 `runtime-host profile set --peer-id ... --peer-route ...`，并通过 `MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL` 提供 setup 创建的 credential。Disable 后重新 enable 会保留 PeerId 和 listener 配置；`peer rotate` 会明确更换 PeerId；卸载 service 会删除 peer key，但保留 State Root。执行 `peer enable --clear-coordination-relays` 可以删除所有已配置的 coordination relay。 Direct-only 路径仍是实验能力，在受限 NAT 或禁用 UDP 的网络中可能失败。它不会替代已有的 TLS、SSH 或 overlay network fallback。Host 默认通过公共 IPFS DHT 的有界 client-only 视图发现 Circuit Relay v2 候选；扣除手动 relay 后，自动池会补足两个已接受 reservation 的目标。手动配置的 relay 始终优先。使用 `peer enable --no-automatic-relay-discovery` 可以关闭这项尽力而为的发现，使用 `peer enable --automatic-relay-discovery` 可以重新开启；关闭不会删除手动 relay。公网 Peer 能观察到发现 连接，也可能拒绝或中止 reservation。只有已接受的 reservation 才会向 Mesh Peer 发布，Maka 仍要求 application stream 升级为直连，不会通过 relay 传输 Session traffic。 Maka 会自动竞速支持的直连 transport，用户不需要选择 QUIC 或 WebRTC。WebRTC 只使用 STUN 发现公网 地址，不会通过 STUN 提供方传输 Session 内容。默认尽力而为策略使用 Cloudflare 公共 STUN；提供方可 观察源 IP 和请求时间，Maka 不保证其可用性。可以在 Desktop 的 Peer Mesh 高级设置中配置，也可以使用 `peer enable --no-public-stun`、`peer enable --default-public-stun`，或重复传入 `peer enable --webrtc-stun ` 来使用自有 STUN。Maka 不使用 TURN；如果所有直连都失败，只有 明确获准的 Mesh 成员可以承载应用流量。 ### Direct TLS 具有稳定网络入口的 Host 使用 TLS： ```sh npm --workspace maka-agent exec -- maka runtime-host serve \ --root /srv/maka \ --websocket-host 0.0.0.0 \ --websocket-port 7443 \ --tls-certificate /etc/maka/tls.crt \ --tls-private-key /etc/maka/tls.key \ --json ``` ### SSH tunnel 当远程机器已经能通过 OpenSSH 访问时，可以让 Runtime Host 只监听 loopback： ```sh npm --workspace maka-agent exec -- maka runtime-host serve \ --root /srv/maka \ --websocket-port 7443 \ --json ``` Maka 不经过 shell，直接运行系统 `ssh`，把 Client 的临时 loopback port 转发到 Host 的 loopback listener。正常的 OpenSSH alias、key、agent 与 host verification 仍然生效；配置了额外 port forwarding 的 Host 条目会被拒绝。Maka 不会修改 SSH config，也不会在删除 Profile 时清理共享的 OpenSSH 状态。 用户主动首次连接时，Desktop 会打开内嵌终端，让 OpenSSH 完成 host-key 确认、密码或 key passphrase 输入；TUI 会在当前终端显示相同提示。后台重连和非交互 CLI 使用 OpenSSH batch mode，因此需要预先配置 SSH key 或 agent。 ### 明确启用明文连接 明文连接不会加密 access credential 或 Session traffic。它只适合可信且隔离的网络，并要求 Host 与 Client 分别明确同意： ```sh npm --workspace maka-agent exec -- maka runtime-host serve \ --root /srv/maka \ --websocket-host 0.0.0.0 \ --websocket-port 7443 \ --allow-insecure-remote \ --json ``` Client Profile 还必须单独持久化明文风险确认。Maka 不会把 TLS 或 SSH 自动降级为明文。复制 service 命令输出的 JSON `rootId`；Client 会用它固定预期的 State Root。 ## 连接 Desktop 打开`设置 → 工作区 → Runtime Host`，选择**添加电脑**并填写 OpenSSH 目标。Desktop 会在交互式 SSH 会话中运行已发布的 setup 命令，保存返回的 credential，验证 tunnel，然后打开远程 Project 选择器。 已有 TLS、SSH 或明确允许的明文 endpoint 可通过**手动配置**添加。 如需从另一台 Desktop 访问当前电脑，可在同一设置页开启**远程访问**。Maka 会保留现有 Local Host 和 State Root，将该 Host 交由操作系统服务管理，并在 Local IPC 之外同时启用 Direct peer listener。将一次性 connection code 提供给另一台 Desktop 即可连接。关闭远程访问只会停止 Direct peer listener；移除后台服务后，Local Host 会重新由 Desktop 管理，所有数据均保留。 Credential 与 Profile 分开存储。Desktop 会让 Local 与每个已启用的 remote Host 独立保持连接，并允许指定一个默认 Host 来创建新 Session；已有 Session 仍使用自己的 Host。Remote connection 失败时仍会显示，但不会中断其他 Host。连接后从该 Host 已注册的 Project 中选择一个；Client 本地目录操作不可用。 对于通过 SSH 管理的电脑，可从其**管理**操作查看已安装版本、服务状态、可用目录和近期日志，也可以启动、重启、修复或卸载服务。卸载会保留远端 State Root，且不会删除 Desktop Profile；移除 Profile 也不会卸载远端服务。手动配置的 direct connection 仍可正常使用，但需要在 Host 机器上管理服务。 ## 连接 TUI 或 CLI 把 target 保存为共享 Profile。只在创建或更新 Profile 时通过环境变量提供 credential： ```sh export MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL='' # Direct TLS maka runtime-host profile set \ --id office --name Office \ --tls-url wss://runtime.example.com:7443/runtime-host \ --expected-root '' # 或 SSH maka runtime-host profile set \ --id office-ssh --name 'Office SSH' \ --ssh-destination user@runtime.example.com \ --ssh-remote-port 7443 \ --expected-root '' # 或明确启用明文连接 maka runtime-host profile set \ --id lab --name Lab \ --plaintext-url ws://192.0.2.10:7443/runtime-host \ --acknowledge-plaintext \ --expected-root '' unset MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL ``` 然后明确选择 Host 上的 Project： ```sh maka --host office --project '' maka run --host office --project '' "总结这个项目" ``` 每个 TUI 或 CLI 进程只连接一个 Profile。TUI 的首次 SSH 连接可以交互；非交互命令要求提前配置认证。 ## 兼容性排查 `RUNTIME_HOST_REMOTE_INCOMPATIBLE` 表示 Client 与远程 Runtime Host 无法安全通信。先比较 Client 与 Host 的 compatibility epoch；当诊断中提供相关信息时，也应检查 Client 和 Host 的 protocol range、composition ID，以及 Host 的 composition revision。 请使用彼此兼容的 Client 和 Host build。更新 Host 后，由 Host 的 operator 重启远程 Runtime Host service，然后重试连接。 Remote Client 不会自动升级或重启 Host、降级 transport、修改 Profile、默认 Host 或 Session，也不会在此诊断中暴露 credential、endpoint、path 或 State Root。 ## 安全边界 - 不要把 credential 放在命令行或 Profile JSON 中。 - 明文连接需要持久的 Client 确认和独立的 Host 启动参数。 - Session response 中的 `hostCwd` 只是 Host metadata，不能通过 Client filesystem 解释。 - Runtime Host protocol operation 不能升级、重启或终止 service process；Desktop 管理使用独立认证的 SSH operator channel。若 durable commit 的结果无法确定，Host 仍会主动 drain；managed service supervisor 会将其重新拉起。 - 在 Host 上使用 `maka runtime-host access revoke --root /srv/maka --credential ` 撤销 credential。