# Hermes on Raspberry Pi

> Source: <https://gist.github.com/sebastienblanc/139c957489696afb194b8b33e6303107>
> Published: 2026-07-12 10:43:22+00:00

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/](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 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`

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

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
```

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, 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
```

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. 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
# Detach: Ctrl+B then D — reattach later with: tmux attach -t hermes
```

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`

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)

**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.

| 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 |

```
# 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
```