Host Helper: setup, health, and independent updates
The Host Helper connects agent events, verified terminal routes, notifications, and mobile decisions without taking ownership of your coding agent.
Outcome
You can identify the installed helper, verify its daemon and hooks, update it independently of the App, and understand when Quick Setup must be run again.
What the Host Helper owns
Your coding agent still runs directly in your shell or tmux session. The Host Helper observes supported provider events, projects a small mobile timeline, holds verified attach routes, and delivers authenticated decisions only when the provider exposes a synchronous control channel.
- Host daemon: serves the authenticated Host API and persistent terminal attach socket.
- Provider hooks: report lifecycle, approval, usage, and review metadata supported by each CLI.
- Notification route: forwards events that need attention to the paired iPhone.
- Updater: checks a signed-by-location manifest, verifies the package SHA-256, and health-checks the new daemon.
Install or repair the current Host Helper
Quick Setup installs SSH/Mosh prerequisites, the versioned Host Helper package, its background service, and supported provider hook definitions. Re-running it is designed to preserve unrelated user hooks.
$ curl -fsSL https://raw.githubusercontent.com/NomadShell/Scripts/main/quick-setup.sh | bash
$ moshline-host version
$ moshline-host doctorRead Doctor as a dependency chain
Doctor checks the path from terminal prerequisites to the daemon, multiplexer adapters, attach socket, and provider hook files. A later failure can be caused by an earlier one.
| Check | What it proves | If it fails |
|---|---|---|
| Mosh client / server | The host can start a Mosh session | Install Mosh or use SSH fallback |
| Host daemon | The authenticated Host API answers with the paired host identity | Inspect the background service and log |
| Multiplexer adapters | The running daemon can expose tmux or Zellij | Fix daemon first, then PATH |
| Terminal attach socket | The daemon created its local control socket | Restart the daemon |
| Provider hooks | Moshline-owned hook definitions are registered | Re-run setup; trust Codex interactively |
Update without waiting for an App release
Host Helper versions are independent of iOS releases. Updater-capable builds check the stable manifest after startup and every six hours. A manual check and an automatic update use the same verified path.
The manifest declares its host protocol range and minimum Node major. The updater downloads the package over HTTPS, verifies its SHA-256, reinstalls hooks and the service, then waits for the target version to answer health checks. A failed health check restores the locally packed previous version.
$ moshline-host version
$ moshline-host update --check
$ moshline-host update --apply
$ moshline-host doctorCompatibility and Node paths
- The App and Host Helper negotiate through a versioned host contract; release manifests declare protocol_min and protocol_max.
- Quick Setup writes the absolute Node and CLI paths into launchd or systemd.
- NVM/asdf paths are valid, but deleting or replacing that exact Node version breaks the saved service path.
- After changing Node installations, re-run Quick Setup instead of hand-editing the generated service.
- A root-owned legacy global npm directory may require one Quick Setup run to migrate to a user-writable install.
Files and trust boundary
| Purpose | macOS path |
|---|---|
| Private host config | ~/.config/moshline/host.json |
| LaunchAgent | ~/Library/LaunchAgents/com.moshline.host.plist |
| Daemon log | ~/Library/Logs/Moshline/host.log |
| Attach socket and local state | ~/.local/share/moshline/ |
Related