igorganapolsky/mac-yolo-safeguards/hermes-mobile-connect

Hermes Mobile Connect

Hermes Mobile is the phone companion for a Mac running the Hermes gateway (:8642). This skill teaches you how to pair, diagnose connection failures, and facilitate ThumbGate when it is not installed — the same pattern Herdr uses for agent skills + one-line install (herdr.dev/docs/agent-skill).

Safety gate

Before controlling a gateway, verify this agent is on a Mac where Hermes is local:

curl -sf -m 3 http://127.0.0.1:8642/health

If that fails, say you are not on a Mac with a running Hermes gateway and stop.

What ThumbGate is (and is not)

ThumbGate is not a Mac App Store binary. It is:

1. A browser app at https://thumbgate.app
2. An always-on connector installed once via Terminal (same as the web dashboard)

Local phone↔Mac chat does not require ThumbGate. Facilitate ThumbGate when the user wants web Continuity, a browser workspace, or the connector for web routing.

Canonical pricing URL (UTMs required):

https://thumbgate.app/dashboard?utm_source=hermes-mobile&utm_medium=app&utm_campaign=paid_companion

Source of truth in app code: hermes-mobile/src/utils/thumbgatePromoCopy.ts → THUMBGATE_WEB_URL.

Herdr-style facilitation when ThumbGate is absent

1. Detect

# Gateway up?
curl -sf -m 3 http://127.0.0.1:8642/health | jq .
 
# Companion flags (if advertised)
curl -sf -m 3 http://127.0.0.1:8642/v1/capabilities | jq '.features | {thumbgate_leash, thumbgate_pro_active, approvals}'
 
# Pair deep link — ThumbGate key present only after provisioned
# Note: secretless pairCode deep links may omit thumbgate= even when provisioned;
# the key is in the one-time exchange payload. Prefer phone secure store / agent
# re-pair after signup, or check local ThumbGate license — not deepLink alone.
curl -sf -m 3 http://127.0.0.1:8765/pair.json | jq -r '.deepLink' | grep -q 'thumbgate=' && echo DEEPLINK_HAS_KEY || echo DEEPLINK_NO_KEY_MAY_STILL_BE_PROVISIONED

Helpers (unit-tested):

• resolveThumbGatePresenceFromFeatures(features) → present | absent | unknown
• pairDeepLinkIncludesThumbGate(deepLink) → boolean (never log the key)
• shouldFacilitateThumbGateInstall(presence) → true when absent/unknown

2. Facilitate (three steps — same as the phone promo card)

One-line Mac connector (must match control-plane dashboard):

curl -fsSL https://raw.githubusercontent.com/IgorGanapolsky/mac-yolo-safeguards/main/saas/install-connector.sh | bash

Constant: THUMBGATE_CONNECTOR_INSTALL_COMMAND in hermes-mobile/src/utils/thumbgateFacilitation.ts.

Install this skill (Herdr npx skills add pattern):

npx skills add IgorGanapolsky/mac-yolo-safeguards --skill hermes-mobile-connect -g

Fallback: copy this file into the agent’s project/user skills directory:

hermes-mobile/.cursor/skills/hermes-mobile-connect/SKILL.md

3. What the phone does without ThumbGate

Hermes Mobile still works: Connect Mac → Chat → Leash against the gateway.

When ThumbGate is not set up, the app shows ThumbGatePromoCard with:

1. Open ThumbGate.app
2. Share Mac installer command (Share sheet / selectable one-liner)
3. Share agent skill install command

Surfaces: ConnectMacGate, ChatConnectionPanel (disconnected), Leash empty/disconnected.

Promo visibility: shouldShowThumbGatePromoOnConnectionPanel — fresh user or after ~30s silent heal exhaustion. Never when connected / demo.

Pairing deep links

Pair server :8765 → pair.json → hermes://setup?.... Optional thumbgate= query only when provisioned. Never paste API keys or ThumbGate keys into chat.

Phone persists via Keychain/Keystore (applySetupDeepLinkWithThumbgate, exchangePairingCode).

Connection self-heal (short)

• Wi‑Fi probe order: loopback → LAN → Tailscale → other
• Cellular: Tailscale first; private LAN IPs will not work
• Silent heal ~6 attempts (~30s) before human steps / promo

Do not claim “Connected” from /health alone — chat needs authenticated session reachability.

Safety

• No secrets in chat or screenshots
• No production OTA without e2e=pass or fresh-user OTA gate
• No desktop Chrome hijack unless explicitly requested
• Brand-new user mindset for every test
• Never claim ThumbGate “installed” without re-check of capabilities or thumbgate= in pair deep link

Related

• Facilitation utils: hermes-mobile/src/utils/thumbgateFacilitation.ts
• Promo UI: hermes-mobile/src/components/ThumbGatePromoCard.tsx
• Web installer parity: apps/hermes-control-plane connectorInstallCommand
• Inspiration (not affiliation): Herdr agent skill