Set Up Tailscale and Hermes Agent on a Raspberry Pi

This guide turns a Raspberry Pi into a small, remotely accessible Hermes Agent machine. We will first connect over the local network, add an SSH key, join the Pi to Tailscale, and then install Hermes Agent.

No router port forwarding is required.

What you need

A Raspberry Pi 4 or 5 with 64-bit Raspberry Pi OS. This guide expects aarch64; 32-bit Raspberry Pi OS is not recommended for Hermes.
A computer on the same local network for the first connection.
SSH enabled when writing the SD card with Raspberry Pi Imager.
A Tailscale account.
A Nous Portal account or an API key for a model provider supported by Hermes.

Replace values such as <PI_USER> and <PI_LAN_IP> in the commands below.

1. Connect to the Pi for the first time

Raspberry Pi Imager lets you set the hostname, username, password, Wi-Fi and SSH options before writing the SD card. After the Pi boots, use one of these methods to find it on your local network.

If you have a screen and keyboard

Open a terminal on the Pi and run:

bash

hostname -I

Use the local IPv4 address from the output, usually beginning with 192.168. or 10..

If the Pi is headless

First try the hostname you chose in Raspberry Pi Imager. The .local address often works without needing to know the IP:

bash

ssh <PI_USER>@<PI_HOSTNAME>.local

For example, if the hostname is hermes-pi:

bash

ssh richard@hermes-pi.local

If that does not resolve, open your router's administration page and look in the connected devices, clients or DHCP leases list for the hostname you set. This is the most reliable headless method.

Once you know the address, connect from your computer:

bash

ssh <PI_USER>@<PI_LAN_IP>

For example:

bash

ssh richard@192.168.1.42

Accept the host fingerprint and enter the password you created in Raspberry Pi Imager.

2. Create and copy an SSH key

Run this on your computer, not the Pi. Press Enter to accept the default file location, then choose a passphrase when prompted.

bash

ssh-keygen -t ed25519 -C "raspberry-pi"

Copy the public key to the Pi:

bash

ssh-copy-id <PI_USER>@<PI_LAN_IP>

Test it before continuing:

bash

ssh <PI_USER>@<PI_LAN_IP>

Keep the original terminal open until the new key-based connection works. Your private key stays on your computer; only the public key is copied to the Pi.

3. Update the Pi

Run these commands on the Pi:

bash

sudo apt update
sudo apt upgrade -y
sudo apt install -y git curl
sudo reboot

Wait for the Pi to restart, then reconnect over the local network.

4. Install Tailscale

The current official Tailscale Linux instructions support Raspberry Pi OS with the following installer:

bash

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Open the URL printed by tailscale up and approve the Pi in your tailnet. Then verify the connection and display its Tailscale addresses:

bash

tailscale status
tailscale ip

Install Tailscale on your computer too, sign in to the same account, and test SSH using either the Tailscale IP or the MagicDNS hostname:

bash

ssh <PI_USER>@<PI_TAILSCALE_IP>
# Or, if MagicDNS is enabled:
ssh <PI_USER>@<PI_HOSTNAME>

You can now reach the Pi away from home without exposing SSH to the public internet.

Optional: let Tailscale manage SSH authentication

The steps above use your normal SSH key over Tailscale. If you prefer Tailscale SSH, enable it on the Pi:

bash

sudo tailscale set --ssh

Tailscale SSH uses your tailnet identity instead of the SSH key for connections to the Pi's Tailscale address. Your tailnet access policy must allow SSH. Skip this option if ordinary SSH keys already meet your needs.

5. Check that the Pi is 64-bit

bash

uname -m

Continue if the result is aarch64. Hermes officially supports Linux on ARM64; if you see armv7l, re-image the SD card with 64-bit Raspberry Pi OS before continuing.

6. Install Hermes Agent

Use the official Hermes Agent installer:

bash

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes doctor

The installer sets up Hermes and its required dependencies under your user account. Do not run the installer with sudo for a normal single-user Pi.

7. Configure and run Hermes

The shortest setup uses Nous Portal:

bash

hermes setup --portal
hermes

Follow the login link and complete the prompts. If you want to use another model provider, run hermes setup instead and enter its API key when prompted. Do not paste API keys into shell scripts or commit them to Git.

At this point Hermes is ready to use through the SSH session.

8. Optional: keep a messaging gateway running

You only need this section if you want to reach Hermes through Telegram, Discord or another messaging service. Configure the gateway, install its user service, and let that service keep running after you log out:

bash

hermes gateway setup
hermes gateway install
sudo loginctl enable-linger "$USER"
hermes gateway start
hermes gateway status

The official Hermes gateway documentation also covers service logs and each supported messaging platform.

Useful checks

If something stops working, these three commands cover most first checks:

bash

tailscale status
hermes doctor
hermes gateway status

If hermes is not found immediately after installation, reload the shell:

bash

source ~/.bashrc

To update Hermes later:

bash

hermes update

That is the complete setup: SSH keys for the first trusted connection, Tailscale for private remote access, and Hermes Agent running on the Pi.