A complete guide: from a blank SD card to a self-improving agent running 24/7 on your home network, reachable via SSH and (optionally) Telegram/Discord/WhatsApp.
Why this works well: Hermes Agent officially supports Linux aarch64 as a Tier 1 platform via the install.sh
installer. The LLM inference runs on a remote provider (Nous Portal, OpenRouter, Anthropic, etc.), so the Pi only handles orchestration, tools, memory, and the messaging gateway — 16 GB of RAM is generous headroom for this.
- Raspberry Pi 5 (16 GB) + official 27 W USB-C power supply (the Pi 5 is picky about power)
- microSD card (32 GB+, A2-rated recommended) — or better, an NVMe SSD with an M.2 HAT if you want durability for a 24/7 machine
- Active Cooler or a case with a fan (the Pi 5 throttles without one under sustained load)
- Your Mac, with Raspberry Pi Imager installed:https://www.raspberrypi.com/software/ - Your home Wi-Fi SSID + password, or an Ethernet cable to the router (Ethernet preferred for an always-on box: more stable, no Wi-Fi power-save issues)
You'll never need a keyboard or monitor on the Pi. Everything is pre-configured from the Imager.
Open
Raspberry Pi Imager on your Mac. -
Device: Raspberry Pi 5. -
OS:Raspberry Pi OS Lite (64-bit)
— under "Raspberry Pi OS (other)". Lite = no desktop, perfect for a headless agent.64-bit is mandatory(Hermes supports aarch64, not armhf). - Storage: your SD card / SSD. - Click
Next → Edit Settings(the OS customization dialog). This is the key step:** General tab:**- Hostname:
hermespi
(you'll reach it ashermespi.local
) - Username: e.g.
sebi
- a strong password Configure wireless LAN: your SSID + password, Wireless LAN country:
FR
(orNO
if the Pi lives in Norway — this matters, it sets legal Wi-Fi channels)- Locale: timezone + keyboard layout (
fr
if you'll ever plug in your AZERTY keyboard)
Services tab:- ✅ Enable SSH - Choose "Allow public-key authentication only" and paste your Mac's public key (recommended), or password authentication to start simple.
To get/create your Mac's public key:
cat ~/.ssh/id_ed25519.pub || ssh-keygen -t ed25519 -C "sebi@mac"
(The
-C "sebi@mac"
is only a comment — a human-readable label attached to the key so you can identify it later. It plays no role in authentication; put whatever you like there, or omit-C
entirely. If your existing key ends with an email address, that's just its comment. Either way, paste thewhole line exactly as printed—ssh-ed25519 AAAA... label
— into Imager, comment included. Don't edit it; trimming by hand risks breaking the key. Copy it cleanly withpbcopy < ~/.ssh/id_ed25519.pub
.) - Hostname: #
Write the image, then insert the card into the Pi.
Ethernet instead of Wi-Fi?Just skip the wireless LAN section and plug the cable in. You can configure both — Ethernet takes priority when connected, Wi-Fi acts as fallback.
Plug in power (and Ethernet if using it). First boot takes ~1–2 minutes (it resizes the filesystem and starts SSH).
Option A — mDNS (easiest): from your Mac:
ping hermespi.local
macOS has Bonjour built in, so this almost always works on a home LAN.
Option B — your router's admin page: look at the DHCP client list for a device named hermespi
and note its IP (e.g. 192.168.1.42
).
Option C — network scan from your Mac:
arp -a | grep -i "b8:27\|dc:a6\|d8:3a\|2c:cf" # common Raspberry Pi MAC prefixes
nmap -sn 192.168.1.0/24
ssh sebi@hermespi.local
ssh sebi@192.168.1.42
Accept the host key fingerprint on first connect. You're in.
Re-flashed the card?The Pi generates new host keys on every fresh install, so your next connection will fail with a loudWARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!
This is expected after a reinstall — clear the stale entry withssh-keygen -R hermespi.local
(andssh-keygen -R <ip>
if you ever connected by IP), then reconnect and accept the new fingerprint.
If you used a password in the Imager, switch to keys now:
ssh-copy-id sebi@hermespi.local
Then on the Pi, disable password login:
sudo nano /etc/ssh/sshd_config
sudo systemctl restart ssh
An always-on agent should not change IP. Two options:
Best: DHCP reservation on your router. In your router's admin UI, pin the Pi's MAC address to a fixed IP (e.g.192.168.1.42
). Zero config on the Pi, survives reinstalls.Alternative: static IP on the Pi(Raspberry Pi OS Bookworm uses NetworkManager):
sudo nmtui # → Edit a connection → set IPv4 to Manual, enter IP/gateway/DNS
Add to ~/.ssh/config
:
Host hermespi
HostName hermespi.local
User sebi
Now it's just ssh hermespi
.
On the Pi:
sudo apt update && sudo apt full-upgrade -y
sudo reboot
Reconnect, then install what the Hermes installer expects (Git is the only hard requirement; curl and xz-utils are needed on Linux because the installer downloads Node.js as a .tar.xz
):
sudo apt install -y git curl xz-utils
Optional but useful for a 24/7 box:
sudo apt install -y tmux htop
One command, as your normal user (not root — the per-user layout is the standard path):
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
The installer handles everything else automatically: uv, Python 3.11, Node.js v22, ripgrep, ffmpeg, the repo clone into ~/.hermes/hermes-agent/
, the virtualenv, and the hermes
command at ~/.local/bin/hermes
.
Headless tip:if you don't need browser automation on the Pi (Playwright + Chromium is the heaviest dependency), you can skip it:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
You can still get web browsing through the Nous Portal
cloud browsertool, which runs remotely — arguably the better fit for a Pi anyway. If youdowant local Chromium, runsudo npx playwright install-deps chromium
first so the system libraries are present.
Then reload your shell:
source ~/.bashrc
hermes doctor # sanity check — should come back clean
The fastest path (one OAuth covers a model + web search, image gen, TTS, and cloud browser via the Tool Gateway):
hermes setup --portal
Since you're on a headless machine, the OAuth flow will print a URL — open it in the browser on your Mac, authenticate, and the CLI picks it up.
Alternatives (bring your own key):
hermes model # interactive provider picker
hermes config set OPENROUTER_API_KEY sk-or-...
Secrets go to ~/.hermes/.env
, settings to ~/.hermes/config.yaml
— hermes config set
routes each value to the right file automatically.
Now chat:
hermes --tui # modern TUI (recommended)
Verify the basics before layering anything on:
❯ What's my disk usage? Show the top 5 largest directories.
Then confirm sessions persist:
hermes -c # resumes the last session
One rule of thumb from the docs worth respecting:get one clean conversation working before adding the gateway, cron, skills, or voice.hermes doctor
→hermes model
→hermes setup
is the recovery sequence when anything feels off.
A note on local models:Hermes requires ≥64K tokens of context. Youcanrun Ollama on a Pi 5, but a model that's both capable enough for agentic tool-calling and holds a 64K context is not realistic on this hardware. Use the Pi as the agent's home and let inference live in the cloud — that's exactly the deployment model Hermes is built for.
This is where the Pi shines: an agent you talk to from Telegram/Discord/Signal/WhatsApp while it works at home, 24/7.
hermes gateway setup # interactive wizard: pick platform, paste bot token, set allowlist
hermes gateway # start it in the foreground to test
hermes gateway status # check state
Telegram is the gentlest first platform: create a bot with @BotFather, paste the token into the wizard, and message your bot.
Create a user service so Hermes runs under your account without root:
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/hermes-gateway.service
[Unit]
Description=Hermes Agent Messaging Gateway
After=network-online.target
Wants=network-online.target
[Service]
ExecStart=%h/.local/bin/hermes gateway
Restart=on-failure
RestartSec=10
[Install]
WantedBy=default.target
Enable it, and allow your user services to run without an active login session (essential for headless):
systemctl --user daemon-reload
systemctl --user enable --now hermes-gateway
sudo loginctl enable-linger $USER # keeps user services alive after you disconnect
Check on it anytime:
systemctl --user status hermes-gateway
journalctl --user -u hermes-gateway -f # live logs
Reboot the Pi (sudo reboot
) and confirm the bot answers without you SSHing in. That's the whole point.
tmux new -s hermes
hermes gateway
Fine for testing; systemd is the right answer for permanent operation.
hermes tools
— enable/disable toolsets per platform (e.g. restrict what the Telegram surface can do vs. the CLI)hermes skills browse
/hermes skills search kubernetes
— the skills hub; every installed skill becomes a/slash
commandCron automations— natural-language scheduling with delivery to any connected platform ("send me a morning briefing on Telegram at 8:00")** MCP servers**— add to~/.hermes/config.yaml
:
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
Terminal sandboxing— for safety on a box that runs unattended, considerhermes config set terminal.backend docker
(install Docker viacurl -fsSL https://get.docker.com | sh
, thensudo usermod -aG docker $USER
). Command approval and allowlists are covered in the Security docs.hermes update
— updates in place (the installer layout auto-detects the right update path)
Thermals: check withvcgencmd measure_temp
. Sustained >80 °C means throttling — get the Active Cooler.Storage endurance: an agent with persistent memory (SQLite FTS5) writes constantly. On SD cards, prefer a quality A2 card and take periodic backups of~/.hermes/
(it holds your config, secrets, sessions, memory, and skills). NVMe via the M.2 HAT is the comfortable long-term option.Backup one-liner from your Mac:
rsync -avz hermespi:~/.hermes/ ~/Backups/hermespi-hermes/
Power: use the official 27 W supply; undervoltage causes mysterious crashes. Checkdmesg | grep -i voltage
if things get weird.
| Symptom | Fix |
|---|---|
hermes: command not found |
|
source ~/.bashrc , or check ~/.local/bin is on PATH |
|
| Empty/broken replies | hermes model — re-verify provider + auth |
| Gateway runs but bot silent | Re-run hermes gateway setup ; check token + allowlist; hermes gateway status |
| Anything else | hermes doctor tells you exactly what's missing |
ssh sebi@hermespi.local
sudo apt update && sudo apt full-upgrade -y && sudo reboot
ssh sebi@hermespi.local
sudo apt install -y git curl xz-utils
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes setup --portal # OAuth via your Mac's browser
hermes --tui # first chat, verify it works
hermes gateway setup # connect Telegram/Discord/...
sudo loginctl enable-linger $USER