I’ll write about Hermes Agent itself and what it can do separately – today it’s about how to run it on FreeBSD.

Yesterday I played around with it on my Arch Linux – now I want a more production setup.

I’ll be running it on my NAS with FreeBSD, and obviously only inside a FreeBSD Jail, since the NAS holds access to important data and backups (the whole series of posts on FreeBSD and NAS starts here – FreeBSD: Home NAS, part 1 – setting up ZFS mirror, there are 15 parts as of now).

The agent’s configuration on Linux is exactly the same – just a simpler setup, so I won’t describe it separately.

But Hermes Agent’s capabilities and a more detailed config – that I’ll do as a separate post, there’s plenty to play with there.

For working with Jails I use Bastille – I’ll write about it separately too, I have a draft.

So, here’s what we’ll do:

• create a FreeBSD Jail
• set up networking
• install Hermes Agent itself
• configure the connection to Telegram
• and install Hermes Agent Web UI

Let’s go.

But first, a bit of off-topic 🙂

Holywar: FreeBSD Jail or “container”?

Quick note here – whether it’s correct to call a FreeBSD Jail a “container”, because I might get flamed for it 🙂

As someone who usually works with Linux, for me a “container” is both a FreeBSD Jail and a Linux Docker container, so in this post I’ll be calling Jails “containers”.

What’s more – even the official documentation for Bastille says:

While reading the documentation and using Bastille, you will find that sometimes “container” is used, and sometimes “jail” is used. These are completely interchangeable, but there is some debate as to which one is more correct. Be that as it may, anytime you read “container” or “jail”, it means a FreeBSD jail.

Besides, my blog readers are mostly Linux users too – so let’s stick with “containers”. And in the separate Bastille post we’ll talk in more detail about Jails in FreeBSD vs Linux containers.

Alright – now let’s get to the install.

Check the FreeBSD version, prepare the container:

root@setevoy-nas:~ # freebsd-version 
14.4-RELEASE-p1

root@setevoy-nas:~ # bastille bootstrap 14.4-RELEASE
...

Create the container itself – a regular FreeBSD one (Bastille also supports Linux, I have a Jail with Opeb WebUI, I’ll write about it eventually, also a draft).

Networking – Bastille VNET, so the container will be reachable from my main network at IP 192.168.0.210:

root@setevoy-nas:~ # bastille create --vnet hermesagent1 14.4-RELEASE 192.168.0.210/24 em0

Attempting to create jail: hermesagent1

Valid IP: 192.168.0.210/24

Creating a thinjail...

...

Check the Jail status:

root@setevoy-nas:~ # bastille list hermesagent1
 JID  Name          Boot  Prio  State  Type   IP Address     Published Ports  Release               Tags
 3    hermesagent1  on    99    Up     thin   192.168.0.210  -                14.4-RELEASE          -

Get inside:

root@setevoy-nas:~ # bastille console hermesagent1

[hermesagent1]:
root@hermesagent1:~ #

Install updates:

root@hermesagent1:~ # pkg update

Install packages needed for Hermes Agent:

root@hermesagent1:~ # pkg install curl bash uv sudo

Check where bash lives – on FreeBSD it’s in /usr/local/bin/, not /usr/bin:

root@hermesagent1:~ # which bash
/usr/local/bin/bash

Create a user for Hermes Agent, set the password:

root@hermesagent1:~ # pw useradd hermes -m -s /usr/local/bin/bash -c "Hermes Agent"
root@hermesagent1:~ # passwd hermes

Enable SSH:

root@hermesagent1:~ # sysrc sshd_enable="YES"
sshd_enable: NO -> YES

root@hermesagent1:~ # service sshd start

Verify the connection from my work laptop:

[setevoy@setevoy-work ~]  $ ssh [email protected]
([email protected]) Password for hermes@hermesagent1:
...
[hermes@hermesagent1 ~]$

Run visudo, add the user there – with password prompt:

hermes ALL=(ALL:ALL) ALL

To run Hermes CLI as root – add this to /root/.profile:

...
# Hermes Agent — ensure ~/.local/bin is on PATH
export PATH="$HOME/.local/bin:$PATH"

That’s it – we can install the agent itself.

Installing Hermes Agent

Install the required libraries – because the automatic Hermes Agent installer doesn’t play very nicely with FreeBSD, so let’s do it by hand:

root@hermesagent1:~ # pkg install -y python3 py311-pip py311-sqlite3 sqlite3 git curl rust pkgconf openssl libffi node22 npm-node22 ripgrep ffmpeg

Run the install – took about 5 minutes:

[hermes@hermesagent1 ~]$ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Once it’s done the installer offers to configure the agent.

Hermes Agent Setup

On Arch Linux I did the quick install, here I went with the full one – to see what’s in there.

All options can be changed later, so it’s not critical.

Documentation – Configuration.

Run the agent setup:

It burns through tokens like crazy, so Claude is a no-go – went with OpenAI and GPT 5.5, works great:

It asks for authentication – opens a link, open it on the laptop with a browser, enter the code:

Set the model to 5.5 – can be changed later via /model (see Slash Commands):

And from there everything can be left at defaults until we get to Messaging.

Telegram setup

Documentation – Telegram Setup.

Plenty of options here, obviously – I’ll stick with Telegram for now:

Head over to @BotFather, create a new bot:

Configure it:

Important – see Step 3: Privacy Mode (Critical for Groups).

Go into its Settings:

Disable Group Privacy:

Grab the bot’s API token:

So we can message the bot – find your User ID via @userinfobot.

If the bot will live in a group or channel – you can find their IDs from the same @userinfobot.

I’m making this bot just for testing, so I’ll leave my user:

And in the “home channel” too:

Done:

Then there are browser and Tools settings – leave everything at defaults, and we’re done:

Telegram and Hermes Agent Gateway on FreeBSD

On Linux Hermes Gateway is enabled simply via systemd – on FreeBSD it’s a bit “by hand” (in quotes – because I had the agent itself do it 🙂 ).

Check the current status:

[hermes@hermesagent1 ~]$ hermes gateway status
✗ Gateway is not running

To start:
  hermes gateway run      # Run in foreground
  hermes gateway install  # Install as user service
  sudo hermes gateway install --system  # Install as boot-time system service

The hermes gateway install command on FreeBSD predictably returned “not supported on this platform“:

[root@hermesagent1 /usr/home/hermes]# /home/hermes/.hermes/hermes-agent/venv/bin/hermes gateway install --system
Service installation not supported on this platform.
Run manually: hermes gateway run

Check where exactly Hermes lives:

[hermes@hermesagent1 ~]$ head -1 "$(command -v hermes)"
#!/home/hermes/.hermes/hermes-agent/venv/bin/python3

Install the python-telegram-bot Python module:

[hermes@hermesagent1 ~]$ /home/hermes/.hermes/hermes-agent/venv/bin/python3 -m pip install python-telegram-bot
Collecting python-telegram-bot
  Downloading python_telegram_bot-22.7-py3-none-any.whl.metadata (17 kB)
...

Try running it manually:

hermes@hermesagent1 ~]$ hermes gateway run
┌─────────────────────────────────────────────────────────┐
│           ⚕ Hermes Gateway Starting...                 │
├─────────────────────────────────────────────────────────┤
│  Messaging platforms + cron scheduler                    │
│  Press Ctrl+C to stop                                   │
└─────────────────────────────────────────────────────────┘

...

And message the bot in Telegram:

Hermes Agent Gateway autostart on FreeBSD

Alright, let’s see if the agent can handle the task of “I’m a lazy engineer, do something nice for me” – let it tell us itself how to add its gateway to autostart on FreeBSD:

Okay.

But I’m so lazy I don’t even want to do copy-paste – let it do everything itself.

We’re in a Jail – so it’s safe:

To create the rc.d script it needs root – asks for the password, since our sudo here requires one:

The script is ready:

The script it wrote – /usr/local/etc/rc.d/hermes_gateway:

#!/bin/sh

# PROVIDE: hermes_gateway
# REQUIRE: LOGIN NETWORKING
# KEYWORD: shutdown

. /etc/rc.subr

name="hermes_gateway"
rcvar="hermes_gateway_enable"

load_rc_config "$name"

: ${hermes_gateway_enable:="NO"}
: ${hermes_gateway_user:="hermes"}
: ${hermes_gateway_home:="/home/hermes"}
: ${hermes_gateway_command:="/home/hermes/.local/bin/hermes"}
: ${hermes_gateway_log:="/var/log/hermes_gateway.log"}

pidfile="/var/run/${name}.pid"
command="/usr/sbin/daemon"
command_args="-f -p ${pidfile} -u ${hermes_gateway_user} -o ${hermes_gateway_log} /usr/bin/env HOME=${hermes_gateway_home} ${hermes_gateway_command} gateway run"

start_cmd="${name}_start"
stop_cmd="${name}_stop"
status_cmd="${name}_status"

hermes_gateway_start()
{
    if [ ! -x "${hermes_gateway_command}" ]; then
        echo "Hermes executable not found or not executable: ${hermes_gateway_command}"
        return 1
    fi

    touch "${hermes_gateway_log}"
    chown "${hermes_gateway_user}" "${hermes_gateway_log}" 2>/dev/null || true

    echo "Starting Hermes gateway."
    ${command} ${command_args}
}

hermes_gateway_stop()
{
    echo "Stopping Hermes gateway."
    if [ -f "${pidfile}" ]; then
        kill "$(cat ${pidfile})" 2>/dev/null || true
        rm -f "${pidfile}"
    else
        pkill -u "${hermes_gateway_user}" -f "${hermes_gateway_command} gateway run" 2>/dev/null || true
    fi
}

hermes_gateway_status()
{
    if [ -f "${pidfile}" ] && kill -0 "$(cat ${pidfile})" 2>/dev/null; then
        echo "Hermes gateway is running as pid $(cat ${pidfile})."
        return 0
    fi

    if pgrep -u "${hermes_gateway_user}" -f "${hermes_gateway_command} gateway run" >/dev/null 2>&1; then
        echo "Hermes gateway is running, but pidfile is missing/stale."
        return 0
    fi

    echo "Hermes gateway is not running."
    return 1
}

run_rc_command "$1"

Verify everything was added to /etc/rc.conf:

root@hermesagent1:~ # cat /etc/rc.conf | grep hermes
hermes_gateway_enable="YES"
hermes_gateway_user="hermes"
hermes_gateway_home="/home/hermes"
hermes_gateway_command="/home/hermes/.local/bin/hermes"
hermes_gateway_log="/var/log/hermes_gateway.log"

Stop the “hermes gateway run” we started by hand earlier, and try starting it via the service:

[hermes@hermesagent1 ~]$ sudo service hermes_gateway start
Starting Hermes gateway.
[hermes@hermesagent1 ~]$ sudo service hermes_gateway status
Hermes gateway is running as pid 60901.

Hermes Agent and Web UI

Googled a few options, for now I went with nesquena/hermes-webui, but you can also take a look at EKKOLearnAI/hermes-web-ui.

Clone the repo:

[hermes@hermesagent1 ~]$ git clone https://github.com/nesquena/hermes-webui.git hermes-webui
[hermes@hermesagent1 ~]$ cd hermes-webui/

To make the WebUI reachable from the network – set $HERMES_WEBUI_HOST:

[hermes@hermesagent1 ~/hermes-webui]$ export HERMES_WEBUI_HOST=0.0.0.0

Start the service:

[hermes@hermesagent1 ~/hermes-webui]$ python3 bootstrap.py 
[bootstrap] Starting Hermes Web UI on http://0.0.0.0:8787
[bootstrap] Web UI is ready: http://0.0.0.0:8787
[bootstrap] Log file: /home/hermes/.hermes/webui/bootstrap-8787.log

Try it in the browser:

In Telegram, ask it to create some kind of reminder:

And we see it in Tasks:

That’s pretty much it.

But here’s one more example of what you can do with the agent.

Hermes Agent Use Case example: creating documentation in DokuWiki

Asked it to walk through all my networks and find the hosts – it ran nmap, scanned everything, put it all into a table:

Then I created a separate user for the agent in my local DokuWiki, enabled XML-RPC in /usr/local/www/dokuwiki/conf/local.php:

$conf['remote'] = 1;
$conf['remoteuser'] = 'hermes-agent';

Asked the agent – and Hermes created a documentation page for me with all my hosts:

Tested it with VictoriaMetrics – it adds metrics great even without VictoriaMetrics Skills (see Claude Code: creating Kubernetes debugging AI Agent for VictoriaMetrics), so it’ll be possible to build automation like “Alertmanager webhook > Hermes > investigate > send result to Telegram”.

In short – the system is interesting, cool – you can build some really fun stuff with it.