{"skill":{"slug":"src","displayName":"Src","summary":"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,...","description":"---\nname: mac-node-bridge\ndescription: 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.\nmetadata: {\"openclaw\":{\"emoji\":\"🔌\"}}\n---\n\n# Mac Node Bridge\n\nUse this skill when your gateway runs on Linux but the real tool lives on a Mac node.\n\nThis 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.\n\n## Use This Skill For\n\n- `imsg`, `remindctl`, `memo`, `things`, `peekaboo`, or other macOS-only CLIs\n- Homebrew-installed business tools that only exist on a Mac node\n- Linux gateway + one or more Mac nodes where you want a stable remote execution path\n- ClawHub-ready skills that should target Macs cleanly instead of mutating bundled Linux assumptions\n\n## Do Not Use This Skill For\n\n- Linux-native CLIs that should simply be installed on the gateway\n- UI-only pairing problems\n- Cases where you do not have passwordless SSH from the gateway to the Mac node\n- Forcing bundled OpenClaw macOS skills to show green on Linux by patching core files\n\n## Requirements\n\n- Linux gateway can SSH to the target Mac node without a password\n- Remote binary exists on the Mac node and is executable\n- The Mac node already has any required macOS privacy permissions granted\n- You know which Mac should own the tool\n\n## Path Rules\n\nUse dynamic paths by default.\n\n- Wrapper install dir defaults to `OPENCLAW_BIN_DIR`, then `XDG_DATA_HOME/openclaw/bin`, then `HOME/.openclaw/bin`\n- Preset installs resolve remote binaries dynamically with `command -v`, remote `brew --prefix`, and common Homebrew prefixes\n- Use `--target-dir` or `--remote-bin` only when you intentionally need to override the defaults\n\n## Trust Model\n\nThis skill assumes:\n\n- the Linux gateway is the orchestrator\n- each Mac node is a separately trusted execution surface\n- cross-host access must be narrow, explicit, and reversible\n\nPlan around these rules:\n\n- use strong, scoped credentials and per-node trust, not one broad shared secret\n- require the Mac side to prove identity before the gateway accepts orchestration signals\n- give each wrapper only the minimum action it needs\n- log cross-host setup, verification, and deployment steps\n- fail soft when a Mac is unavailable; do not crash the whole system\n\nRead [references/security-model.md](references/security-model.md) before publishing or extending this skill.\n\n## Workflow\n\n### 1. Pick The Owning Mac\n\nDefault pattern:\n\n- `M1`: always-on services like `imsg`\n- `MacBook Pro`: heavier interactive or business tooling\n\nIf you are unsure, verify first:\n\n```bash\nscripts/verify-node-tool.sh --host agent1@mac-mini.local --tool imsg\nscripts/verify-node-tool.sh --host agent2@macbook-pro.local --tool remindctl\n```\n\nIf the tool lives outside the normal shell path or Homebrew defaults, pass an explicit path:\n\n```bash\nscripts/verify-node-tool.sh --host agent2@macbook-pro.local --bin /custom/path/remindctl\n```\n\n### 2. Install A Wrapper On The Gateway\n\nFor a known tool preset:\n\n```bash\nscripts/install-preset.sh \\\n  --tool imsg \\\n  --host agent1@mac-mini.local\n```\n\nOr install a generic wrapper:\n\n```bash\nscripts/install-wrapper.sh \\\n  --name remindctl-mbp \\\n  --host agent2@macbook-pro.local \\\n  --remote-bin /opt/homebrew/bin/remindctl\n```\n\nOverride the wrapper directory only when you need a non-default layout:\n\n```bash\nscripts/install-preset.sh \\\n  --tool memo \\\n  --host agent1@mac-mini.local \\\n  --target-dir \"$HOME/.local/bin\"\n```\n\n### 3. Verify The Wrapper\n\n```bash\n\"${OPENCLAW_BIN_DIR:-${XDG_DATA_HOME:-$HOME/.openclaw}/openclaw/bin}\"/imsg chats --limit 1\n\"${OPENCLAW_BIN_DIR:-${XDG_DATA_HOME:-$HOME/.openclaw}/openclaw/bin}\"/remindctl-mbp lists\n```\n\nIf 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.\n\n### 4. Publish Wrapper-Aware Skills\n\nWhen building a new ClawHub skill on top of this bridge:\n\n- call the wrapper through a configurable path contract, not a user-specific absolute home path\n- document which node owns the tool\n- keep secrets and tokens on the node or gateway config, not in the skill folder\n- treat the wrapper as the stable contract\n\nRead [references/publish-pattern.md](references/publish-pattern.md) before turning a one-off wrapper into a public skill.\n\n## Security Rules\n\n- Use a dedicated SSH key for gateway-to-node wrappers whenever possible\n- Use non-root accounts on the Mac nodes\n- Prefer one wrapper per tool per node instead of a single unrestricted shell bridge\n- Never store API tokens, app secrets, or OAuth cookies in the skill folder\n- Never patch bundled OpenClaw skill files just to make Linux appear to support macOS tools\n- Keep wrapper names explicit, for example `imsg-m1` or `remindctl-mbp`, when multiple Macs may own similar tools\n- Log who installed or rotated a wrapper and when\n- Keep a rollback path: remove one wrapper, do not tear down the whole node\n- If a tool needs more than read or one explicit action, define that permission boundary in the published skill\n- If a wrapper depends on a Mac-only GUI permission, verify it explicitly and report a degraded-but-safe state instead of pretending success\n\n## Common Presets\n\nSupported presets in `scripts/install-preset.sh`:\n\n- `imsg`\n- `remindctl`\n- `memo`\n- `things`\n- `peekaboo`\n- `brew`\n- `gh`\n\nThe preset installer resolves the remote binary dynamically. If resolution fails, pass `--remote-bin` explicitly.\n\n## Examples\n\n### Wire iMessage Through M1\n\n```bash\nscripts/install-preset.sh \\\n  --tool imsg \\\n  --host agent1@mac-mini.local\n```\n\n### Wire Reminders Through MacBook Pro\n\n```bash\nscripts/install-preset.sh \\\n  --tool remindctl \\\n  --host agent2@macbook-pro.local \\\n  --name remindctl-mbp\n```\n\n### Use A Custom Binary\n\n```bash\nscripts/install-wrapper.sh \\\n  --name my-mac-tool \\\n  --host agent2@macbook-pro.local \\\n  --remote-bin /custom/tools/my-mac-tool\n```\n\n## Files\n\n- `scripts/install-wrapper.sh`: create one secure SSH wrapper for a remote binary\n- `scripts/install-preset.sh`: install wrappers for common macOS tools with dynamic remote resolution\n- `scripts/verify-node-tool.sh`: verify SSH and remote binary availability by path or tool name\n- `references/publish-pattern.md`: how to build a publishable wrapper-aware skill on top\n- `references/security-model.md`: trust boundaries, least privilege, audit trail, and rollback expectations\n","tags":{"latest":"0.6.1"},"stats":{"comments":0,"downloads":484,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1774039191638,"updatedAt":1778492072793},"latestVersion":{"version":"0.6.1","createdAt":1774039191638,"changelog":"- Initial public documentation for *mac-node-bridge*, enabling Linux OpenClaw gateways to securely run macOS-only tools through SSH wrappers on connected Mac nodes.\n- Details workflow for wrapper installation, verification, and publishing wrapper-aware skills without patching OpenClaw core.\n- Lists requirements, supported tools, and security rules for using Mac nodes as remote execution targets.\n- Provides common usage patterns and strong trust model recommendations.\n- Includes scripts for dynamic installation and verification of remote macOS binaries.","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"matthewxmurphy","userId":"s17e4vez0qmckg0a0a8j3sq4rd885nyq","displayName":"Matthew Murphy","image":"https://avatars.githubusercontent.com/u/110652790?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090011835}}