Hermes Agent IoT

Lightweight Hermes Agent for Raspberry Pi 2 / ARMv7, MQTT, Home Assistant, robotics, and low-resource edge AI.

Hermes Agent IoT is an IoT/robotics-focused fork of NousResearch/hermes-agent. The maintained pi2-lite branch focuses on constrained Raspberry Pi and edge deployments while preserving the upstream Hermes Agent runtime and ecosystem.

版本與升級注意事項： 本版識別為 0.22.5.post3，使用保留 MIT 署名的獨立 browser-harness-hermes-compat 與 Pillow 13 修補。請先確認 對應 PyPI 版本 已列出後，再執行下方固定版本安裝；若尚未上架，請使用來源 checkout，不把來源合併或輔助套件上架當成 Hermes 已發布。舊 0.22.2.post1 不含這輪安全修補。升級建議使用全新 venv，不要混裝官方／獨立 browser distributions；見 相容性與遷移說明 及 同步驗證紀錄。

相關影片

• YouTube Shorts

Why Hermes Agent IoT?

• Raspberry Pi 2 / ARMv7: verified low-resource installation path for 1 GB-class hardware.
• IoT profiles: dependency profiles for MQTT, Home Assistant, MCP/ACP, and remote-first RAG.
• Edge-first deployment: keep heavy AI inference remote while the Raspberry Pi handles agent orchestration and device integration.
• Robotics direction: foundation for GPIO, I2C, PWM, sensors, actuators, and robotics skills.
• Upstream-aware: IoT and ARMv7 compatibility changes are reviewed separately from fast-moving upstream development.

Quick Start — Raspberry Pi 2

Hermes Agent IoT requires Python >=3.11,<3.15. Install it in a virtual environment:

python3 --version
python3 -m venv ~/.venvs/hermes-iot-0.22.5
source ~/.venvs/hermes-iot-0.22.5/bin/activate
python -m pip install --upgrade pip
python -m pip install 'hermes-agent-iot[minimal]==0.22.5.post3'
python -m pip check

hermes-iot setup --profile minimal
hermes-iot profile show
hermes setup model
hermes

Do not use system pip, sudo pip, or --break-system-packages.

Source checkout

Use the maintained pi2-lite branch when you need the complete repository assets:

git clone --branch pi2-lite --depth 1 \
  https://github.com/matttest0080-prog/hermes-agent-iot.git
cd hermes-agent-iot
bash setup-pi2-minimal.sh --profile minimal
source ~/.hermes-venv/bin/activate
hermes setup model
hermes

Keep the clone directory. The source installer uses an editable Python installation, so moving or deleting the checkout can break the environment.

Install Profiles

Keep the PyPI extra and setup profile aligned. For example:

python -m pip install 'hermes-agent-iot[iot]==0.22.5.post3'
hermes-iot setup --profile iot

full and dev are not recommended for Raspberry Pi 2 / 1 GB systems.

Project Status

Documentation

• IoT Project Overview — project goals, support status, profiles, and roadmap.
• Raspberry Pi 2 Quick Start — dependency matrix, configuration profiles, and Pi2 safety guidance.
• Raspberry Pi 2 Manual — detailed Pi2 deployment documentation.
• Robotics — robotics integration notes.
• Security Policy — vulnerability reporting and security guidance.
• Upstream Hermes Agent documentation — general Hermes Agent features, providers, gateways, desktop/server usage, and integrations.

Upstream vs Hermes Agent IoT

This fork may intentionally lag upstream main while dependency changes, IoT patches, and ARMv7 compatibility are reviewed and validated. For general desktop/server Hermes Agent usage, prefer the upstream project.

發行與驗證紀錄

• 本版 package／tag 識別：hermes-agent-iot 0.22.5.post3／iot-v0.22.5.post3。
• PyPI 對應版本與正式檔案雜湊／GitHub release 與 tag。是否已發行以實際頁面與 CI 為準，不以此來源文件取代發布證據。
• Pi 2B 實機基準：Rev 1.1、ARMv7、921 MiB RAM、Python 3.13.5。本輪 registry 相容依賴的隔離候選完成五 profiles hash 解析、正常 minimal 安裝與 pip check、10 項 installed-wheel smoke、12 項 SQLite deadline／逐 byte 回滾控制。五個 profiles 不等於全都已實裝；localhost fixture 不是實際模型、MQTT／HA 或長期負載驗收。
• 從舊版升級請使用前述新 venv，保留舊環境與服務供回復。pip install --upgrade 不一定移除舊 orphan browser-harness，混裝會造成 Pillow 要求衝突或同名模組互相覆寫。

歷史已發布驗證：0.22.2.post1

以下保留舊版 receipt，不是 0.22.5.post3 的 artifact 或安全驗證：

• PyPI: hermes-agent-iot 0.22.2.post1
• Tag: iot-v0.22.2.post1
• Commit: 2c08f4ec97445d8f26ab5c35515b2f94652aaddf
• Wheel: hermes_agent_iot-0.22.2.post1-py3-none-any.whl
• Wheel SHA-256: e46b7049940f14928d0dd014f44494126faca261363e9240fa700fb84d13fd8f
• Workflow: https://github.com/matttest0080-prog/hermes-agent-iot/actions/runs/39356318990
• Python: >=3.11,<3.15
• Physical validation: Raspberry Pi 2 Model B Rev 1.1, 32-bit ARMv7, 921 MiB RAM, Python 3.13.5

The minimal wheel baseline was clean-installed from public PyPI on physical Raspberry Pi 2 hardware on 2026-10-20: pip check clean, hermes --version = 0.22.2.post1, wheel SHA-256 matched, and a one-shot agent turn returned PI2-OK in 81.6 s using a remote model over SSH. That verifies the Pi 2 client/runtime path, not local inference on the Pi. Heavier optional extras require hardware appropriate to their dependency set.

Updating a Pi2 Source Installation

Always keep updates pinned to the pi2-lite branch:

cd ~/hermes-agent-iot
source ~/.hermes-venv/bin/activate

git status --short
git switch pi2-lite
git fetch origin pi2-lite
git merge --ff-only origin/pi2-lite

bash setup-pi2-minimal.sh --profile minimal

Replace minimal with the profile originally installed. In IoT release 0.20.4 and later, a bare hermes update detects the hermes-agent-iot distribution and defaults to pi2-lite; an explicit --branch pi2-lite remains useful in automation for auditability. Rerun the profile installer after a source update.

Roadmap

• Raspberry Pi 2 / ARMv7 installation path
• Low-resource dependency profile
• IoT dependency profile
• MQTT / Home Assistant integration path
• Public PyPI package
• Physical Raspberry Pi 2 validation
• GPIO abstraction
• I2C device abstraction
• PWM / servo control
• Sensor plugin framework
• Robotics skill framework
• ESP32 MQTT bridge
• Raspberry Pi 3 / 4 / 5 validation matrix

Upstream Desktop / Server Installation

Hermes Agent IoT is primarily for Raspberry Pi and edge deployments. For general desktop or server use, install the upstream Hermes Agent.

Windows (native PowerShell)

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The source installer delegates Python 3.14, Node.js, npm, ripgrep, FFmpeg, and Python dependencies to PM. If Git is absent, it stages the verified Git for Windows archive in Hermes' tool store. It does not replace your system Git. See installation methods for the separate MSIX/App Installer package and its update ownership.

Linux / macOS / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Android / Termux: A signed APT repository is available for aarch64 devices, with a stable channel (tagged releases) and a prerelease canary channel. The package includes Python, Node.js, and the TUI. Use the Termux guide, not the desktop/server installer script.

These upstream installers do not install this fork's Pi2-specific profiles or IoT packaging.

About Hermes Agent

Hermes Agent is the self-improving AI agent developed by Nous Research. It provides a terminal interface, persistent learning and memory, scheduled automations, subagents, multiple execution backends, messaging gateways, and support for multiple LLM providers.

Hermes Agent IoT does not replace the upstream project. It adapts that foundation for Raspberry Pi 2, ARMv7, low-resource edge nodes, MQTT/Home Assistant environments, and future robotics integrations.

License and Attribution

Hermes Agent IoT is derived from NousResearch/hermes-agent and follows this repository's MIT License. Preserve upstream copyright and attribution when redistributing derived work.