HHermes Explained

Skills

BOOT.md

A user-defined gateway hook pattern that runs instructions from ~/.hermes/BOOT.md at gateway startup.

Importance 3/52 backlinks4 source refs

BOOT.md

What it is

A user-defined gateway hook pattern that runs instructions from ~/.hermes/BOOT.md at gateway startup.

In plain terms

A note taped to a building’s front door for whichever security guard opens up that morning — check the alarm log, note anything odd, then carry on — is roughly what BOOT.md gives Hermes’s gateway. It’s a plain-language checklist a person writes and saves themselves, which a background process reads and runs once every time the gateway restarts, rather than a routine the agent decides on its own to remember.

Why it matters

BOOT.md is not a built-in Hermes startup file. The documented pattern is a user-created gateway hook under ~/.hermes/hooks/boot-md/ that listens for gateway:startup, reads ~/.hermes/BOOT.md, and starts a one-shot AIAgent in a background thread; an empty or missing file returns without doing work. That distinction matters because the behavior exists only after the operator installs the hook, and its model, credentials, delivery target, and [SILENT] convention are all defined by the hook implementation rather than by a hidden runtime rule.

How it works

When the gateway process starts, HookRegistry.discover_and_load() walks every subdirectory under ~/.hermes/hooks/, and any folder whose HOOK.yaml declares the gateway:startup event gets its handler.py wired in (gateway/hooks.py). The boot-md handler is ordinary Python the operator writes: it reads ~/.hermes/BOOT.md, and its background agent is built using the gateway’s actual resolved model and provider credentials — via helpers like _resolve_gateway_model() and _resolve_runtime_agent_kwargs() — rather than bare defaults, since an unconfigured AIAgent() would fail authentication against any non-default endpoint (gateway/run.py). That credential-matching requirement is exactly why Hermes documents this as a pattern you wire up by hand instead of shipping it as a built-in: a generic built-in hook would have to guess every operator’s provider setup, so the docs hand you the working handler.py to adapt instead.

A concrete example

An operator writes a three-line BOOT.md: check hermes cron list for overnight job failures, scan a deploy log for ERROR lines from the last 24 hours, and reply with only [SILENT] if both come back clean. The next time the gateway restarts — after a crash, a server reboot, or a manual hermes gateway restart — the hook fires automatically, spawns the checklist agent in the background, and either a summary lands in the configured Discord channel or nothing arrives at all because the night was uneventful.

How it connects

This note belongs to the Skills family. Its closest neighboring concepts are: soul.md, Hooks, Agent Runtime, Personal OS.

Source evidence

  • file:website/docs/user-guide/features/hooks.md#BOOT.md — Explicit Source Map scope boundary: The documentation file is outside the approved Core scope.
  • vendor/hermes-agent/gateway/hooks.py#<file> — Structural Source Map fallback for gateway/hooks.py. A core source file in the Plugin Manager and Hooks structure within Skills and Plugins.
  • vendor/hermes-agent/gateway/run.py:7062-7068#GatewayRunner.start — Verified Source Map evidence for GatewayRunner. At Gateway startup, each adapter message handler is bound to the central _handle_message pipeline. The central handler covers authorization, commands, sessions, context, agent execution, and response delivery; before any await it acquires an active-session lease and creates a run generation.
  • vendor/hermes-agent/run_agent.py:1892-1902#AIAgent._flush_messages_to_session_db — Verified Source Map evidence for AIAgent. AIAgent uses thin forwarding methods to delegate system-prompt construction to agent.system_prompt.build_system_prompt, API kwargs construction to the chat-completion helper, and streaming requests to interruptible_streaming_api_call.

Workflows

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • Ten Underused Hermes Features That Reveal Its Real Power