Repository navigation
[Tracking] Managed remote Runtime Host onboarding and lifecycle #3228
Description
English
Problem
Runtime Host already provides the remote execution, authentication, reconnect, multi-Host Desktop, Host-scoped Settings, and remote Project foundations tracked by #2522. Desktop can now prepare a supported Linux computer through interactive SSH, install an exact Maka CLI release, pair the Client, verify the connection, and continue to remote Project selection.
The managed lifecycle now covers per-Host service inspection and repair, credential maintenance, safe exact-package updates, channel discovery, bounded policy reconciliation, equivalent Linux systemd and macOS LaunchAgent backends, scheduler-backed reconciliation, and the Desktop update-policy and status surface. The planned lifecycle is complete.
Desired outcome
Desktop should provide one coherent per-computer lifecycle: guided onboarding, service health and repair, credential maintenance, safe updates, and explicit removal or uninstall actions with clear ownership boundaries.
The same management contract must remain usable from CLI and TUI, and must preserve identical update semantics across the Linux and macOS service backends.
Stable boundaries
- SSH is the management plane for installation, service control, updates, credentials, and diagnostics. Runtime Host remains the only Session and execution data plane.
- The OS service manager owns the persistent process. Runtime Host never overwrites or updates its own executable.
- Foreground management actions are explicit, idempotent transactions with durable recovery boundaries. Periodic desired-state reconciliation is reserved for later unattended update policy, where continuous convergence has a concrete product need.
- Deployed versions are always exact. Channel names only resolve a desired exact version.
- Update policy defaults to manual. Automatic updates must wait for a safe maintenance point and respect storage compatibility.
- Credential secrets are delivered once and stored only by the Client credential store. Management UI exposes metadata, rotation, and revocation rather than secrets.
- Removing a Desktop profile, uninstalling the remote service, and deleting the State Root are three separate operations.
- The default SSH path uses the system OpenSSH client and a loopback Runtime Host listener. Maka does not modify the user's SSH config or implement a second SSH stack.
Delivery plan
- Platform-neutral service lifecycle contract and Linux systemd user backend: install, status, start, stop, restart, readiness verification, and clean uninstall while retaining the State Root (feat(cli): manage Linux Runtime Host services #3205)
- Add an idempotent remote bootstrap, exact-release deployment, and pairing contract with structured progress and stable errors (Add an idempotent managed Runtime Host setup contract #3229, feat(cli): set up managed remote Runtime Hosts #3230)
- Add the Desktop Add Computer wizard over interactive system SSH (feat(desktop): add managed remote Runtime Host onboarding over SSH #3233, feat(desktop): add managed remote Runtime Host onboarding #3236)
- Add per-Host Desktop service status, bounded logs, start/restart, repair, and clean uninstall (feat(desktop): manage installed remote Runtime Host services #3281, feat(desktop): manage remote runtime host services #3282)
- Add per-Host credential metadata, rotation, and revocation (feat(desktop): manage access credentials for remote Runtime Hosts #3418, feat(desktop): manage remote runtime host credentials #3419)
- Add safe side-by-side version switching, health checks, failure recovery, and manual updates (feat(runtime-host): add managed Host retirement #3557, feat(runtime-host): add safe managed Host updates #3591; retirement hardening in fix(runtime-host): bind managed retirement to one service generation #3600 and fix(runtime-host): fence State Root before service retirement #3602)
- Add read-only channel/exact-version discovery and fail-closed unattended-update admission (feat(runtime-host): discover managed Host updates safely #3664, feat(runtime-host): discover managed Host updates #3667)
- Connect admitted discovery candidates to the existing verified managed update transaction (feat(runtime-host): apply discovered managed Host updates safely #3679, feat(runtime-host): apply verified managed updates #3687)
- Add
manual | fixed | latest | nextpolicy with bounded one-shot reconciliation (feat(runtime-host): add managed update reconciliation policy #3717, feat(runtime-host): add managed update reconciliation #3720) - Add Linux systemd and macOS LaunchAgent scheduler adapters that reuse the one-shot reconciler (feat(runtime-host): schedule managed update reconciliation #3747)
- Add the per-Host Desktop update-policy and update-status surface (feat(desktop): manage per-Host Runtime Host update policy #3768, feat(desktop): manage Runtime Host update policy #3771)
- Add a macOS LaunchAgent backend that reuses the same lifecycle and management contract (feat(runtime-host): support managed services on macOS #3659)
Each slice should remain independently useful. Update automation must not block initial onboarding, and Desktop UI must not duplicate service or credential authority.
Definition of done
- A user can prepare a supported Linux remote computer from Desktop without manually copying a port, Root ID, or credential
- Password, host-key, passphrase, and MFA prompts can be completed through the existing bounded interactive SSH surface
- Setup is retryable and does not leave duplicate services, profiles, or credentials
- Desktop saves a Profile only after the service and authenticated Runtime Host connection have been verified
- Users can distinguish removing the computer from Desktop, uninstalling Maka-managed service files, and explicitly deleting all Host data
- Manual and automatic updates never silently cross an unsupported storage compatibility boundary
- CLI and TUI can use the same machine-readable management contract without adopting Desktop's multi-Host UI
- Linux and macOS backends share lifecycle semantics rather than separate product state machines
Non-goals
- A federated Runtime Host or cross-Host Session migration
- A custom SSH implementation, silent
sudo, or automatic installation of Node.js - Opening the Runtime Host listener to the public network by default
- Treating uninstall as permission to delete the State Root
- A Windows persistent-service backend without a concrete product requirement
- A cloud pairing or rendezvous service before local SSH onboarding proves insufficient
简体中文
问题
#2522 已经完成 Runtime Host 的远程执行、认证、重连、Desktop Multi-Host、Host-scoped Settings 与远程 Project 等基础能力。Desktop 现在也可以通过交互式 SSH 准备受支持的 Linux 电脑，安装精确的 Maka CLI release、配对 Client、验证连接，并继续选择远程 Project。
托管生命周期现已覆盖 per-Host 服务检查与修复、credential 维护、安全的精确 package 更新、channel discovery、有界的 policy reconciliation、语义一致的 Linux systemd 与 macOS LaunchAgent backend、scheduler 驱动的 reconciliation，以及 Desktop 更新策略与状态界面。计划内的生命周期工作现已完成。
期望结果
Desktop 应提供一套连贯的 per-computer 生命周期：引导式 onboarding、服务健康与修复、credential 维护、安全更新，以及所有权边界清晰的移除或卸载操作。
同一套管理契约仍须可供 CLI 与 TUI 使用，并在 Linux 与 macOS service backend 上保持一致的更新语义。
稳定边界
- SSH 是安装、服务控制、更新、credential 和诊断的管理面；Runtime Host 仍是唯一的 Session 与 execution 数据面
- 持久进程由 OS service manager 管理；Runtime Host 不能覆盖或更新自己的可执行文件
- 前台管理操作采用显式、幂等并带持久恢复边界的事务；周期性的 desired-state reconcile 留给后续无人值守更新策略，仅在持续收敛有明确产品需求时引入
- 实际部署永远使用精确版本；频道名称只用于解析期望的精确版本
- 更新策略默认是手动；自动更新必须等待安全维护点，并遵守 storage compatibility
- Credential secret 只交付一次，并且只存入 Client credential store；管理界面只展示 metadata、轮换和撤销
- 从 Desktop 移除 Profile、卸载远程 service、删除 State Root 是三个独立操作
- 默认 SSH 路径使用系统 OpenSSH 和远端 loopback Runtime Host listener；Maka 不修改用户 SSH config，也不实现第二套 SSH
交付计划
- 平台无关的 service lifecycle contract 与 Linux systemd user backend，包括 install、status、start、stop、restart、readiness 验证，以及保留 State Root 的干净卸载（feat(cli): manage Linux Runtime Host services #3205）
- 增加幂等的远程 bootstrap、精确 release deployment 与配对契约，并提供结构化进度和稳定错误（Add an idempotent managed Runtime Host setup contract #3229、feat(cli): set up managed remote Runtime Hosts #3230）
- 通过交互式 system SSH 增加 Desktop 添加电脑 向导（feat(desktop): add managed remote Runtime Host onboarding over SSH #3233、feat(desktop): add managed remote Runtime Host onboarding #3236）
- 增加 per-Host Desktop 服务状态、有界日志、启动/重启、修复与干净卸载（feat(desktop): manage installed remote Runtime Host services #3281、feat(desktop): manage remote runtime host services #3282）
- 增加 per-Host credential metadata、轮换与撤销（feat(desktop): manage access credentials for remote Runtime Hosts #3418、feat(desktop): manage remote runtime host credentials #3419）
- 增加安全的 side-by-side 版本切换、健康检查、失败恢复与手动更新（feat(runtime-host): add managed Host retirement #3557、feat(runtime-host): add safe managed Host updates #3591；retirement hardening 见 fix(runtime-host): bind managed retirement to one service generation #3600 与 fix(runtime-host): fence State Root before service retirement #3602）
- 增加只读的 channel/精确版本发现，并对无人值守更新采用 fail-closed 准入（feat(runtime-host): discover managed Host updates safely #3664、feat(runtime-host): discover managed Host updates #3667）
- 将通过准入的 discovery candidate 接入现有已验证的 managed update transaction（feat(runtime-host): apply discovered managed Host updates safely #3679、feat(runtime-host): apply verified managed updates #3687）
- 增加
manual | fixed | latest | next策略与有界的一次性 reconcile（feat(runtime-host): add managed update reconciliation policy #3717、feat(runtime-host): add managed update reconciliation #3720） - 增加复用 one-shot reconciler 的 Linux systemd 与 macOS LaunchAgent scheduler adapter（feat(runtime-host): schedule managed update reconciliation #3747）
- 增加 per-Host Desktop 更新策略和更新状态界面（feat(desktop): manage per-Host Runtime Host update policy #3768、feat(desktop): manage Runtime Host update policy #3771）
- 增加复用相同 lifecycle 与管理契约的 macOS LaunchAgent backend（feat(runtime-host): support managed services on macOS #3659）
每个 slice 都应能够独立提供价值。自动更新不能阻塞首次 onboarding，Desktop UI 也不能复制 service 或 credential authority。
完成标准
- 用户可以直接在 Desktop 中准备受支持的 Linux 远程电脑，无需手工复制 port、Root ID 或 credential
- Password、host key、passphrase 与 MFA prompt 可以通过现有的有界交互式 SSH 界面完成
- Setup 可以安全重试，不会留下重复 service、Profile 或 credential
- 只有 service 和经过认证的 Runtime Host 连接都验证成功后，Desktop 才保存 Profile
- 用户能够明确区分从 Desktop 移除电脑、卸载 Maka 托管的 service 文件，以及显式删除全部 Host 数据
- 手动或自动更新都不能静默跨越不受支持的 storage compatibility 边界
- CLI 与 TUI 可以使用同一套机器可读管理契约，而无需复制 Desktop Multi-Host UI
- Linux 与 macOS backend 共享 lifecycle 语义，不形成两套产品状态机
非目标
- Federated Runtime Host 或跨 Host Session migration
- 自研 SSH、静默执行
sudo，或自动安装 Node.js - 默认把 Runtime Host listener 开放到公网
- 把卸载视为删除 State Root 的授权
- 在没有明确产品需求前实现 Windows persistent-service backend
- 在本地 SSH onboarding 被证明不足前引入云端 pairing 或 rendezvous service
Activity
M4n5ter commentedon Aug 25, 2026
English
The planned work is complete:
Closing this tracking issue. Future lifecycle enhancements should be scoped in separate issues so this completed milestone does not become an indefinitely growing backlog.
简体中文
计划内工作已经全部完成：
因此关闭本 tracking issue。后续 lifecycle 增强应单独立项，避免已完成的 milestone 继续变成无限扩张的 backlog。