Deploying Hermes Agent on a Raspberry Pi 5 (16 GB)

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.

0. What you need

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)

1. Flash Raspberry Pi OS (headless, SSH pre-enabled)

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 as hermespi.local)
- Username: e.g. sebi + a strong password
- Configure wireless LAN: your SSID + password, Wireless LAN country: FR (or NO 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 the whole 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 with pbcopy < ~/.ssh/id_ed25519.pub.)
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.

2. First boot and finding the Pi on your network

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
# or, if you have nmap (brew install nmap):
nmap -sn 192.168.1.0/24

3. SSH in

ssh sebi@hermespi.local
# or by IP:
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 loud WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! This is expected after a reinstall — clear the stale entry with ssh-keygen -R hermespi.local (and ssh-keygen -R <ip> if you ever connected by IP), then reconnect and accept the new fingerprint.

Recommended hardening (5 minutes)

If you used a password in the Imager, switch to keys now:

# From your Mac:
ssh-copy-id sebi@hermespi.local

Then on the Pi, disable password login:

sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
sudo systemctl restart ssh

Give the Pi a stable address

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

Handy SSH shortcut on your Mac

Add to ~/.ssh/config:

Host hermespi
    HostName hermespi.local
    User sebi

Now it's just ssh hermespi.

4. Update the system and install prerequisites

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

5. Install Hermes Agent

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 browser tool, which runs remotely — arguably the better fit for a Pi anyway. If you do want local Chromium, run sudo 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

6. Choose a provider and run your first chat

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-...
# or Anthropic, OpenAI, DeepSeek, Hugging Face, custom endpoints...

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)
# or: hermes     # classic CLI

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. You can run 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.

7. Turn it into an always-on agent (messaging gateway)

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.

Run the gateway as a systemd service (survives reboots)

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.

Alternative: tmux (quick and dirty)

tmux new -s hermes
hermes gateway
# Detach: Ctrl+B then D — reattach later with: tmux attach -t hermes

Fine for testing; systemd is the right answer for permanent operation.

8. Next layers (once stable)

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 command
Cron 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, consider hermes config set terminal.backend docker (install Docker via curl -fsSL https://get.docker.com | sh, then sudo 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)

9. Pi-specific housekeeping

Thermals: check with vcgencmd 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. Check dmesg | grep -i voltage if things get weird.

Quick troubleshooting

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

TL;DR command sequence

# Mac: flash Pi OS Lite 64-bit with Imager (hostname=hermespi, SSH on, Wi-Fi set)
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/...
# then install the systemd user service from section 7
sudo loginctl enable-linger $USER

sebastienblanc/hermes-raspi.md

Select an option

No results found