Skill: matthewxmurphy/mac-node-bridge (version 0.6.1)

--- name: mac-node-bridge description: Bridge macOS-only tools into a Linux OpenClaw gateway via SSH wrappers and connected Mac nodes. Use when a Linux gateway needs to run imsg, remindctl, memo, things, peekaboo, brew-backed CLIs, or other node-local macOS binaries without patching OpenClaw core or pretending Linux can run macOS skills directly. metadata: {"openclaw":{"emoji":"🔌"}} --- # Mac Node Bridge Use this skill when your gateway runs on Linux but the real tool lives on a Mac node. This skill does not patch bundled OpenClaw skills. It creates explicit SSH wrappers and verification steps so a Linux gateway can call macOS binaries on connected nodes in a way that is publishable, repeatable, and auditable. ## Use This Skill For - `imsg`, `remindctl`, `memo`, `things`, `peekaboo`, or other macOS-only CLIs - Homebrew-installed business tools that only exist on a Mac node - Linux gateway + one or more Mac nodes where you want a stable remote execution path - ClawHub-ready skills that should target Macs cleanly instead of mutating bundled Linux assumptions ## Do Not Use This Skill For - Linux-native CLIs that should simply be installed on the gateway - UI-only pairing problems - Cases where you do not have passwordless SSH from the gateway to the Mac node - Forcing bundled OpenClaw macOS skills to show green on Linux by patching core files ## Requirements - Linux gateway can SSH to the target Mac node without a password - Remote binary exists on the Mac node and is executable - The Mac node already has any required macOS privacy permissions granted - You know which Mac should own the tool ## Path Rules Use dynamic paths by default. - Wrapper install dir defaults to `OPENCLAW_BIN_DIR`, then `XDG_DATA_HOME/openclaw/bin`, then `HOME/.openclaw/bin` - Preset installs resolve remote binaries dynamically with `command -v`, remote `brew --prefix`, and common Homebrew prefixes - Use `--target-dir` or `--remote-bin` only when you intentionally need to override the defaults ## Trust Model This skill assumes: - the Linux gateway is the orchestrator - each Mac node is a separately trusted execution surface - cross-host access must be narrow, explicit, and reversible Plan around these rules: - use strong, scoped credentials and per-node trust, not one broad shared secret - require the Mac side to prove identity before the gateway accepts orchestration signals - give each wrapper only the minimum action it needs - log cross-host setup, verification, and deployment steps - fail soft when a Mac is unavailable; do not crash the whole system Read [references/security-model.md](references/security-model.md) before publishing or extending this skill. ## Workflow ### 1. Pick The Owning Mac Default pattern: - `M1`: always-on services like `imsg` - `MacBook Pro`: heavier interactive or business tooling If you are unsure, verify first: ```bash scripts/verify-node-tool.sh --host [REDACTED_SECRET] --tool imsg scripts/verify-node-tool.sh --host [REDACTED_SECRET] --tool remindctl ``` If the tool lives outside the normal shell path or Homebrew defaults, pass an explicit path: ```bash scripts/verify-node-tool.sh --host [REDACTED_SECRET] --bin /custom/path/remindctl ``` ### 2. Install A Wrapper On The Gateway For a known tool preset: ```bash scripts/install-preset.sh \ --tool imsg \ --host [REDACTED_SECRET] ``` Or install a generic wrapper: ```bash scripts/install-wrapper.sh \ --name remindctl-mbp \ --host [REDACTED_SECRET] \ --remote-bin /opt/homebrew/bin/remindctl ``` Override the wrapper directory only when you need a non-default layout: ```bash scripts/install-preset.sh \ --tool memo \ --host [REDACTED_SECRET] \ --target-dir "$HOME/.local/bin" ``` ### 3. Verify The Wrapper ```bash "${OPENCLAW_BIN_DIR:-${XDG_DATA_HOME:-$HOME/.openclaw}/openclaw/bin}"/imsg chats --limit 1 "${OPENCLAW_BIN_DIR:-${XDG_DATA_HOME:-$HOME/.openclaw}/openclaw/bin}"/remindctl-mbp lists ``` If the wrapper works but a bundled OpenClaw skill still shows gray, that is expected on a Linux gateway. Use the wrapper-backed workflow or publish a wrapper-aware skill instead of patching OpenClaw core. ### 4. Publish Wrapper-Aware Skills When building a new ClawHub skill on top of this bridge: - call the wrapper through a configurable path contract, not a user-specific absolute home path - document which node owns the tool - keep secrets and tokens on the node or gateway config, not in the skill folder - treat the wrapper as the stable contract Read [references/publish-pattern.md](references/publish-pattern.md) before turning a one-off wrapper into a public skill. ## Security Rules - Use a dedicated SSH key for gateway-to-node wrappers whenever possible - Use non-root accounts on the Mac nodes - Prefer one wrapper per tool per node instead of a single unrestricted shell bridge - Never store API tokens, app secrets, or OAuth cookies in the skill folder - Never patch bundled OpenClaw skill files just to make Linux appear to support macOS tools - Keep wrapper names explicit, for example `imsg-m1` or `remindctl-mbp`, when multiple Macs may own similar tools - Log who installed or rotated a wrapper and when - Keep a rollback path: remove one wrapper, do not tear down the whole node - If a tool needs more than read or one explicit action, define that permission boundary in the published skill - If a wrapper depends on a Mac-only GUI permission, verify it explicitly and report a degraded-but-safe state instead of pretending success ## Common Presets Supported presets in `scripts/install-preset.sh`: - `imsg` - `remindctl` - `memo` - `things` - `peekaboo` - `brew` - `gh` The preset installer resolves the remote binary dynamically. If resolution fails, pass `--remote-bin` explicitly. ## Examples ### Wire iMessage Through M1 ```bash scripts/install-preset.sh \ --tool imsg \ --host [REDACTED_SECRET] ``` ### Wire Reminders Through MacBook Pro ```bash scripts/install-preset.sh \ --tool remindctl \ --host [REDACTED_SECRET] \ --name remindctl-mbp ``` ### Use A Custom Binary ```bash scripts/install-wrapper.sh \ --name my-mac-tool \ --host [REDACTED_SECRET] \ --remote-bin /custom/tools/my-mac-tool ``` ## Files - `scripts/install-wrapper.sh`: create one secure SSH wrapper for a remote binary - `scripts/install-preset.sh`: install wrappers for common macOS tools with dynamic remote resolution - `scripts/verify-node-tool.sh`: verify SSH and remote binary availability by path or tool name - `references/publish-pattern.md`: how to build a publishable wrapper-aware skill on top - `references/security-model.md`: trust boundaries, least privilege, audit trail, and rollback expectations


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)