Connection Hooks
Run your own shell scripts when a HearthGate tunnel connects or disconnects, with timeout safeguards and loop protection.
Run useful scripts around a secure session
Connection Hooks let HearthGate run a shell script when a tunnel connects or disconnects. Use them for small, local automations: notify yourself, start or pause an app, keep the Mac awake, lock the screen after a session, or append a simple audit row.
Common hook ideas include Slack or webhook alerts, macOS notifications, CSV session logs, Apple Music, Spotify, and Podcasts pause scripts, and cleanup actions after the SSH/VNC session ends.
Hooks are meant to be practical and bounded. HearthGate applies timeout safeguards and loop protection, so a stuck script does not become the remote-access experience.
| Event | When it runs | Good uses | Behavior |
|---|---|---|---|
| On connect | Runs as soon as the secured session is up. | Start a helper app, pause local audio, send a banner, or notify Slack. | Immediate. Use it for things you want the moment access begins. |
| After connect | Runs after the session has stayed stable for the delay you choose. | Start caffeinate, mount a drive, begin a backup, or launch a longer workflow. | If the connection drops before the delay ends, the pending hook is cancelled. |
| On disconnect | Runs when the secured session starts closing. | Record the disconnect, stop a temporary guard, or send a quick session-ended notice. | Immediate. Use it for fast cleanup or logging. |
| After disconnect | Runs after the session has stayed ended for the delay you choose. | Lock the screen, send a final team notification, or resume a local workflow. | If the user reconnects inside the delay window, the pending hook is cancelled. |
Session state matters: hooks fire when the secure session state is complete. A partial connection or a brief flap will not trigger delayed hooks, so your automation can wait for a real connect or a real disconnect instead of reacting to noise.
Example scripts
The public examples live on GitHub so you can read, copy, fork, and adapt them before pointing HearthGate at a script file.
Open example hooksgit clone https://github.com/codnamacs/hearthgate-hooks.git ~/HearthGate-Hookschmod +x ~/HearthGate-Hooks/01-macos-notification.shWhat HearthGate passes in
HEARTHGATE_EVENTThe event name: on-connect, after-connect, on-disconnect, or after-disconnect.
HEARTHGATE_SESSION_DURATION_SECAvailable on disconnect events when HearthGate knows how long the session ran.
HEARTHGATE_HOOK_TIMEOUT_SECThe timeout window HearthGate gives the hook before it is considered stalled.
Controls for each slot
Each hook slot has the same small control surface, so a notification hook and a cleanup hook stay easy to reason about.
| Control | What it does | Why it matters |
|---|---|---|
| Master toggle | Turns each slot on or off. | When a slot is off, the script never runs even if a file is selected. |
| Choose script | Picks the script file from disk. | Use a local executable shell script such as .sh, .bash, or .zsh. |
| Delay | Waits before firing the two After slots. | Useful for avoiding automation during brief reconnects or network flaps. |
| Timeout | Limits how long a script can run. | A timed-out hook is reported in the UI, but the remote session itself keeps its own path. |
| Test run | Runs the selected script manually with simulated hook variables. | Good for checking notifications, logs, and permissions before a real session. |
| Last run | Shows the last time the slot actually fired. | A quick sanity check that the hook is wired to the event you expect. |
Runs as your user
Hook scripts run with your normal user permissions, not as root. They cannot touch system files unless your user could already do so.
Failures are visible
A non-zero exit is shown as an error, and a timeout is shown as timed out. The SSH/VNC session is not broken by the hook result.
File types stay narrow
HearthGate accepts shell-script style files such as .sh, .bash, and .zsh. The shebang decides the interpreter.
Loop guard
If a hook tries to create another HearthGate session, HearthGate detects the recursion and refuses to fire the hook again. This loop protection keeps remote-access automation from calling itself repeatedly.
macOS notification
Show a local banner when a remote session starts or ends.
Voice announcement
Let the Mac speak the session state out loud for across-the-room awareness.
Slack webhook
Send connect and disconnect notices to a team channel.
Pause music
Stop Music, Spotify, or Podcasts when screen sharing begins.
Caffeinate guard
Keep the Mac awake while a remote session is active.
Lock screen on disconnect
Return the Mac to a locked state when the session ends.
CSV access log
Append connect and disconnect events to a local spreadsheet-friendly file.
Rule of thumb: keep hook scripts short, readable, and local-first. Avoid storing secrets in public scripts; pass tokens through environment variables or private files on the Mac.