| name | claude-remote-control |
| description | Install, self-heal, or clean up the Claude Code remote-control daemon behind the claude.ai/code Remote Control dropdown on kai-server, kai-desktop-tower (WSL + Windows), and the Macs. Use when a host is missing from the dropdown, shows duplicate rows, drops out overnight with exec claude not found / status 127, or when standing up a new host. Aliases - remote control dropdown, kai-server daemon, node-tooling-ensure, node orphan, status 127 claude not found, claude.service cleanup. |
Claude remote-control daemon
Status: 🛠 Runbook | Last updated: 2026-07-03
What she is
A per-host daemon (claude remote-control) that pre-registers a named session so the
host appears as a row in the claude.ai/code Remote Control dropdown. One row per host,
keyed off --remote-control-session-name-prefix. kai-server runs it under systemd, WSL
under systemd-in-WSL2, Windows native under a Scheduled Task, and the two Macs under a
user LaunchAgent. Host table + canonical --name values live in
references/claude-remote-control.md.
Which procedure
- Install a new or existing host, or recover a latched daemon -> install path.
Install is idempotent and self-repairing: it patches
~/.claude.json, reinstalls
units, runs node-tooling-ensure inline, and reset-faileds a latched unit before
restarting. Re-running it is the fastest fix for most breakage. See
references/claude-remote-control-install.md.
- Self-heal when kai-server vanishes overnight with
exec: claude: not found and
status=127 -> the nvm node-bump orphan. The three-part fix (node-tooling-ensure
timer at 02:50, restart precheck gate, Restart=always unit) is already installed by
the installer. Manual reset-failed recipe in
references/claude-remote-control-self-heal.md.
- Clean up stale or duplicate dropdown rows, or retire the legacy
systemctl --user claude.service -> references/claude-remote-control-cleanup.md.
Per-platform install
Pick the installer for the host, then run it from the checked-out repo:
- kai-server (Linux systemd):
scripts/claude-remote-control-install.sh
- kai-desktop-tower WSL side:
scripts/claude-remote-control-install-wsl.sh (also
writes /etc/wsl.conf hostname -> needs wsl --shutdown once)
- Windows native:
scripts/claude-remote-control-install-windows.ps1 (PowerShell)
- macOS (both Macs):
scripts/claude-remote-control-install-macos.sh, with
CLAUDE_RC_NAME=kai-mac-kapwing for the Kapwing work Mac
Ward wrapper for the kai-server path: ward exec claude-remote-control-install.
Supporting scripts
scripts/kai-server-node-tooling-ensure.sh - re-materializes node globals
(@anthropic-ai/claude-code, mcporter) after an nvm bump. Extend its GLOBALS
array when a unit starts depending on a new global CLI.scripts/claude-remote-control-restart-precheck.sh - gates the 03:00 restart on
claude resolving via source nvm.sh.
Read the matching reference before acting - the docs carry the exact commands,
prereqs, and rationale. This file is the map, not the procedure.
