OpenClaw Series · Part 6a Install Guide

How to Install Hermes Agent
on Home Assistant OS

A complete setup guide for running Hermes Agent as a Home Assistant add-on on a Raspberry Pi 5 — Telegram alerts, no-LLM scheduled jobs, SOUL.md identity, and zero ongoing infrastructure cost.

🥧Raspberry Pi 5 recommended

🏠HAOS 2024.x or later

⏱~30 min setup time

💸Free to install LLM API key needed

Overview

What is Hermes Agent?

Hermes Agent is an open-source AI agent framework by NousResearch. It runs as a persistent, always-on agent that you reach through Telegram (or Discord, Slack, WhatsApp), and executes tasks by running scripts on the host system. Unlike chatbot interfaces, Hermes is designed for continuous operation — it stays running, remembers context across conversations via SQLite, and responds to commands instantly.

On Home Assistant OS, Hermes installs as a sidebar add-on with a built-in web terminal. It can control smart home devices, run automation scripts, and act as a personal command interface — all from a Telegram message.

🧠

Persistent memory

SQLite FTS5 long-term memory survives add-on restarts and HAOS updates. Conversation history is searchable.

🪪

SOUL.md identity

A Markdown file defines who the agent is, what it says, and what it executes immediately. Loaded fresh every message. Version-controlled like code.

📡

Multi-platform messaging

Telegram, Discord, WhatsApp, Slack, Signal — configure multiple channels simultaneously via the gateway.

⏰

No-LLM scheduled alerts

Cron jobs that run scripts and deliver output directly — zero tokens, zero model cost. The killer feature for always-on monitoring.

🖥

Sidebar web terminal

Full CLI access from the Home Assistant sidebar via a persistent tmux session — no SSH client needed for day-to-day work.

🔌

OpenAI-compatible API

Connect Open WebUI, SillyTavern, or any OpenAI-compatible frontend to Hermes via /v1/ endpoints.

ℹ️

Coming from OpenClaw? This guide covers a fresh Hermes install. If you're migrating an existing OpenClaw setup — skills, scripts, memory, and SOUL.md — see Part 6: The Migration Guide after completing this install.

The Standout Feature

Scheduled Alerts with Zero LLM Cost

Most AI agent setups have a hidden problem: every scheduled alert burns API tokens on the LLM, even when the message content is completely determined by a script. Hermes solves this with no-agent cron mode — scheduled jobs that run a shell script and deliver its output directly, skipping the model entirely.

⚡ Why this matters

Your daily portfolio check shouldn't cost LLM tokens

If the script already knows what to say — run the data, format the output, send it — there's no reasoning needed. Routing that through a language model adds latency, cost, and unpredictability with no benefit.

Standard cron approach

−Schedule fires → LLM wakes up
−Tokens consumed every run
−Model may rephrase output
−Rate limits block mid-day alerts
−Monthly cost scales with frequency

Hermes no-agent mode

✓Schedule fires → script runs directly
✓Zero tokens, zero model spend
✓Output is exactly what script emits
✓No rate limits — runs forever
✓Cost: $0 per scheduled alert

The mechanism is elegant: if the script emits output, it's delivered to Telegram. If stdout is empty, the tick is silent. Your alert only fires when something actually needs your attention.

⏰ No-agent cron — how it works

Scheduler tick (every N min)

→

Run your script

→

stdout → Telegram ✓

Scheduler tick

→

Run script (nothing to report)

→

Empty stdout → silent ✓

LLM is never invoked. Zero tokens on every tick, regardless of frequency.

Setting up a no-LLM scheduled alert — CLI

# Write your alert script
cat > ~/.hermes/scripts/my-alert.sh << 'EOF'
#!/usr/bin/env bash
# Add your check logic here.
# Print output = message gets sent.
# Print nothing = silent tick.
echo "Daily update: $(date '+%H:%M')"
EOF
chmod +x ~/.hermes/scripts/my-alert.sh

# Schedule it — no_agent skips the LLM entirely
hermes cron create "0 9 * * *" \
  --no-agent --script my-alert.sh \
  --deliver telegram \
  --name "daily-alert"

# Verify
hermes cron list

💡

Or just ask Hermes in Telegram "Ping me on Telegram if disk is over 90% every 15 minutes" — Hermes writes the script, schedules it with --no-agent, and confirms the job ID. No shell required.

Script behaviour	Result
Exit 0, non-empty stdout	Output delivered verbatim to Telegram
Exit 0, empty stdout	Silent tick — no message sent
Non-zero exit code	Error alert delivered (broken watchdog doesn't fail silently)
Script timeout	Timeout error alert delivered

Before You Begin

Prerequisites

☐Raspberry Pi 5 (4GB or 8GB recommended) running Home Assistant OS. Pi 4 works but Pi 5 is significantly faster for agent workloads.
☐SSH access to your Home Assistant instance — enable via Settings → Add-ons → Advanced SSH & Web Terminal add-on.
☐A Telegram account and a bot token from @BotFather — send /newbot, follow the prompts, copy the token.
☐Your Telegram numeric user ID — get it from @userinfobot.
☐An LLM API key for conversational interactions. DeepSeek Flash is recommended — sign up at platform.deepseek.com. Note: scheduled no-LLM alerts don't need this.
☐Send at least one message to your new Telegram bot before setup — Hermes needs a chat history entry to identify your channel.

Installation

Step-by-Step Install Guide

This guide uses the WolframRavenwolf/hermes-ha-addon — the community-maintained Home Assistant add-on that packages Hermes Agent with a built-in web terminal, HTTPS access, and full persistence across updates.

Add the repository to Home Assistant

Go to Settings → Apps → Install app. Click the three-dot menu (⋮) in the top right and select Repositories. Add:

https://github.com/WolframRavenwolf/hermes-ha-addon

Click Add, close the dialog, wait 30 seconds and refresh. Hermes Agent will appear in the add-on store.

⚠️

Not showing up? Do a full browser refresh. If still absent, check the URL for typos — it must be exact.

Install Hermes Agent

Click Hermes Agent in the add-on store, then Install. Takes 2–5 minutes on a Pi 5 — do not navigate away. Do not start it yet.

Configure the add-on

Go to Settings → Apps → Hermes Agent → Configuration. The key options to set before first start:

Configuration options (Home Assistant UI)

# API keys — written to ~/.hermes/.env on each start
env_vars:
  - "DEEPSEEK_API_KEY=your_key_here"
  # Add others as needed:
  # - "ANTHROPIC_API_KEY=sk-ant-..."
  # - "OPENAI_API_KEY=sk-..."

# Optional: point to your HA instance for device control
hass_url: "http://homeassistant.local:8123"
homeassistant_token: "your_ha_token"

# Optional: enable the sidebar web terminal
enable_terminal: true

⚠️

API key security The env_vars field is the correct place for API keys — they're written to ~/.hermes/.env (chmod 600) on each start. Never put keys in public config or share your .env file.

Start the add-on and run the setup wizard

Click Start. Then open Hermes Agent from the Home Assistant sidebar — a setup wizard runs automatically on first start. It will ask for your model provider, API key confirmation, and messaging platform.

💡

Wizard shortcuts You can also run hermes setup in the sidebar terminal at any time to re-run the wizard, or hermes gateway setup specifically to configure Telegram and other messaging platforms.

Configure Telegram via the gateway

In the sidebar terminal, run the Telegram setup:

hermes gateway setup

Select Telegram, enter your bot token from BotFather, and your numeric user ID. Send a message to your bot in Telegram — the gateway will confirm the connection and show your chat ID.

⚠️

Bot must have a message first If the gateway can't find your chat ID, open Telegram and send any message to your bot, then retry hermes gateway setup.

Confirm HERMES_HOME and file layout

On HAOS, ~ resolves to /config/ inside the container — not a user home directory. This trips up almost everyone coming from a standard Linux install.

Verify paths in the sidebar terminal

echo $HERMES_HOME
# Returns: /config/.hermes
# NOT: ~/.hermes

ls /config/.hermes/
# Expect: SOUL.md  config.yaml
#         .env  memories/  state.db  skills/

hermes doctor
# Flags missing deps or config issues

📌

HAOS path rule Every file path in SOUL.md command tables, shell scripts, and cron jobs must use /config/.hermes/ — never ~/.hermes/. Always confirm with echo $HERMES_HOME before writing any path.

Write your SOUL.md

The default identity is generic. Replace it — SOUL.md is loaded fresh every message, no restart needed:

Minimal SOUL.md starter

cat > /config/.hermes/SOUL.md << 'EOF'
# Your Agent — Identity

You are [Name], a personal AI agent running
on a Raspberry Pi 5 inside Home Assistant OS.

## Voice
Concise. Direct. Answer first, explain second.
Never say "Great question!" or "As an AI...".

## Commands — Execute Immediately
# | run report |
#   bash /config/.hermes/scripts/report.sh |
EOF

echo "SOUL.md written — test via Telegram"

Enable auto-start and watchdog

On the Hermes Agent add-on page, toggle Start on boot and Watchdog to on. Watchdog auto-restarts the add-on if it crashes. Verify after a reboot:

# Safe HAOS reboot
ha host reboot

# After reboot — confirm running:
ha addons info local_hermes_agent | grep state
# Expected: state: started

Verification

Confirming Everything Works

☐Telegram bot responds to messages within 5 seconds
☐echo $HERMES_HOME returns /config/.hermes in the sidebar terminal
☐hermes doctor reports no errors
☐ls /config/.hermes/ shows SOUL.md, config.yaml, .env
☐SOUL.md edits are reflected in the next Telegram response — no restart needed
☐Add-on restarts automatically after ha host reboot
☐Send /status in Telegram — Hermes reports current model and memory state

✅

Test a no-LLM alert right now Run hermes cron create "every 1m" --no-agent --script /config/.hermes/scripts/my-alert.sh --deliver telegram --name "test" in the terminal. You should get a Telegram message within 60 seconds with zero LLM usage. Remove it with hermes cron list then hermes cron remove <job_id>.

Where to Go Next

Adding Scripts and Scheduled Alerts

Put all your scripts in /config/.hermes/scripts/ — this is the only directory Hermes will execute from. Map them to Telegram commands in your SOUL.md command table, or schedule them as no-LLM cron jobs:

Example — HA status check on demand + daily no-LLM alert

# Create a script
mkdir -p /config/.hermes/scripts
cat > /config/.hermes/scripts/ha-status.sh << 'EOF'
#!/bin/bash
ha core info | grep -E "version|state"
EOF
chmod +x /config/.hermes/scripts/ha-status.sh

# Add to SOUL.md command table for on-demand use:
# | ha status |
#   bash /config/.hermes/scripts/ha-status.sh |

# OR schedule it as a daily no-LLM alert at 9am:
hermes cron create "0 9 * * *" \
  --no-agent --script ha-status.sh \
  --deliver telegram --name "daily-ha-status"

Ready for the full migration walkthrough?

Part 6 covers a complete migration from OpenClaw to Hermes — SOUL.md design, path reconciliation, script migration, DeepSeek Flash setup, and six lessons from running this in production.

↗ Part 6 — From OpenClaw to Hermes: The Migration

Search This Blog

World's Better Half