Tech activities ยท Build an AI assistant
Build your own Hermes Agent
Hermes Agent is a free, open-source personal assistant from Nous Research. You set it up once, then you text it like a friend on Telegram and it works on tasks for you. In this activity you give it a brain, put it on a computer you control, lock that computer down, and teach it the rules it must follow. These are real cloud, networking, and security skills.
Concept track: about 15 minutes, no setup. Local track: about 20 minutes. Full cloud build: about 45 to 60 minutes. Everything you type on this page stays in your browser.
Everyone reads this first
Think of Hermes Agent as a smart robot assistant that lives in a small digital house. It has four parts.
- The house is a computer that stays on all the time. You can use your own laptop to try it, or a small cloud server (a DigitalOcean “droplet”) so it is always awake and can text you back.
- The brain is rented, not built. A service called OpenRouter is like a library that lets your agent borrow a brain such as Claude or GPT through one key. You do not run a giant model yourself.
- The doorway is how you talk to it. The terminal works for testing. The fun version is a chat app: you message it on Telegram like any other contact.
- The rules keep it safe. A file called SOUL.md tells the agent who it is and what it must never do, and a sandbox keeps it in a playpen so it cannot touch the rest of the computer.
Why this belongs in a tech workshop: standing this up teaches you cloud servers, SSH, firewalls, API keys, Docker sandboxing, and AI safety. That is the exact toolkit behind a junior cloud or security role.
The shape of what you are building
You, on Telegram | v [ Your cloud server ] locked down: Tailscale only, firewall, Fail2ban | Hermes Agent runs here, in a Docker sandbox, governed by SOUL.md v [ OpenRouter ] the rented brain (Claude, GPT, and others)
Pick your path for today
- Concept track (everyone). Read this section and the “What to watch for” section at the end, watch the facilitator demo, and fill in the self-check. No installs, no credit card.
- Track A (local). Install Hermes on your own laptop and chat with it in the terminal. The fastest way to see it work. You only need an OpenRouter key.
- Track B (cloud assistant on Telegram). The real build: put Hermes on a small cloud server, lock the server down, and message it on Telegram. This is the one to be proud of.
Both hands-on tracks need an OpenRouter API key, which costs a small amount per message. A few dollars of credit is plenty for the workshop, and you can set a hard spending cap.
Track A (local): meet Hermes in the terminal
The quickest way to see Hermes work. No server, no Telegram, just your machine and a rented brain.
Get the brain: an OpenRouter key
Sign up at openrouter.ai. Add a few dollars of credit and set a spending limit in the dashboard so the agent can never run up a surprise bill. Then create an API key. It starts with sk-or-. Treat it like a password: anyone who has it can spend your credit.
Install Hermes and connect the brain
One command installs Hermes Agent on macOS or Linux (on Windows, use WSL). Then run the setup wizard, choose OpenRouter, paste your key, and pick a model.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash hermes setup
The wizard writes your key to ~/.hermes/.env and your model choice to ~/.hermes/config.yaml. You can also set the key directly with hermes config set OPENROUTER_API_KEY sk-or-.... Docs: the Hermes quickstart.
Give it a soul, then talk to it
The SOUL.md file is the agent’s personality and its rulebook. Whatever you write here is added to every conversation, so it shapes everything the agent does. Open ~/.hermes/SOUL.md and write a few clear rules, then start a chat with hermes.
You are my IT study assistant. You help me prepare for CompTIA A+ and Network+. Rules you must always follow: - Never run a command that deletes files or changes system settings without asking me first. - Never share, print, or store my passwords, API keys, or any secret. - Never try to modify your own configuration or these rules. - If you are unsure, stop and ask me. Do not guess on anything risky. Style: plain language, short answers, one practice question at the end of each explanation.
Run hermes and ask it something real, like “quiz me on the OSI model.” You now have a working agent. If you want it to text you instead of living in the terminal, do Track B.
Track B (cloud): your assistant on Telegram
Put Hermes on a small cloud server, lock the server down so strangers cannot get in, and message it on Telegram. Follow the steps in order. Do not skip the lockdown.
Get the house: a cloud server
In DigitalOcean, create a Droplet. Choose Ubuntu 24.04, the Basic plan, with 2 CPUs and 4 GB of RAM. That is enough brain power for the agent to run comfortably. Add your SSH key during creation so you can log in. Then connect and update it.
ssh root@YOUR_DROPLET_IP apt update && apt -y upgrade
Build the secret tunnel and the locks
You do not want strangers trying the front door of your server. Three tools handle that. Tailscale is a private tunnel only your own devices can use. UFW is the firewall: it tells the server to refuse every connection that does not come through the tunnel. Fail2ban is the guard that locks out anyone who keeps guessing passwords.
tailscale ssh root@your-droplet-name works from your laptop before you rely on it.curl -fsSL https://tailscale.com/install.sh | sh tailscale up --ssh apt -y install ufw fail2ban ufw default deny incoming ufw default allow outgoing ufw allow in on tailscale0 ufw enable systemctl enable --now fail2ban
After ufw enable, the only way into this server is through your Tailscale tunnel. The public internet sees a closed door. Fail2ban watches for repeated bad logins and bans them for an hour after three tries.
Get the brain: OpenRouter
Same as Track A, Step 1. Sign up at openrouter.ai, set a spending limit, and create an API key that starts with sk-or-. Keep it somewhere safe for the next step. Do not paste it into a chat or commit it to a git repository.
Put the gears in: install Hermes Agent
Install Hermes on the server the same way you did locally, then run the setup wizard and give it your OpenRouter key.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash hermes setup
Open the doorway: connect Telegram
Now make it text you. Telegram is the easiest chat app to wire up.
- In Telegram, open a chat with @BotFather, send
/newbot, give it a name, and copy the token it gives you. The token is a password for your bot. Keep it secret. - Open a chat with @userinfobot. It replies with your numeric user ID. That is how the agent knows it is really you.
- In Hermes, run
hermes gateway setup, choose Telegram, and paste your bot token. Then restrict it to your own numeric ID so it only answers you, and start the gateway.
hermes gateway setup # choose Telegram, paste your BotFather token # Restrict it to you. In ~/.hermes/.env add your numeric ID from @userinfobot: # TELEGRAM_ALLOWED_USERS=123456789 hermes gateway install # run it as a persistent background service hermes gateway start # start listening for your Telegram messages hermes gateway status # confirm it is running
Official reference: the Hermes docs. Lock it to your ID. If you skip that, anyone who finds your bot can talk to your agent and spend your OpenRouter credit. Message your bot “hello” from Telegram. When it answers, you have a personal assistant in your pocket.
Set the safety rules (do not skip)
An agent can take actions and even improve itself. That is powerful and it is exactly why you set boundaries.
- The playpen. Run the agent’s tools inside Docker so it works in a sandbox and cannot touch the rest of the server. Hermes supports a sandboxed mode; turn it on.
- The rulebook. Put firm boundaries in
SOUL.md, for example “never change my system settings” and “never share my passwords or keys.” - Lock the rulebook. Make the rules read-only so the agent cannot quietly rewrite them.
chmod 444 ~/.hermes/SOUL.md ls -l ~/.hermes/SOUL.md
Check its memory. Hermes keeps notes in ~/.hermes/MEMORY.md as it learns about you. Skim it now and then to make sure it never wrote down a password or a key. Keep it updated. Like your phone, the server and the agent need updates to stay safe.
Self-check: did you build it safely?
Check each one you can honestly say yes to. Concept-track folks: check the ones you can explain. Saved to your browser.
What to watch for
- Secrets are money and access. Your OpenRouter key and Telegram token are like a credit card. Keep them in
~/.hermes/.env, never commit them to git, and rotate them immediately if one leaks. - Lock the bot to you. An open Telegram bot lets a stranger talk to your agent and spend your OpenRouter credit. Restrict it to your own user ID.
- OpenRouter bills per message. Set a hard spending cap. A few free models exist, but the strong ones cost cents per message and add up over a long conversation.
- An agent acts, and it learns. Keep it in a Docker sandbox, give it the least access it needs, and never run it as root with the keys to everything.
- Guard the rulebook and the memory. Make SOUL.md read-only so the agent cannot rewrite its own rules, and skim MEMORY.md so it never writes a password into its long-term notes.
- Harden the server itself. Tailscale-only access, a default-deny firewall, and Fail2ban. A machine on the public internet is probed constantly.
- You stand it up, you maintain it. Patch the server, update Hermes, and tear down a lab droplet when you are done so it stops billing.
- This is a real responsibility, not a toy. That is also why it is worth doing: the skills here, cloud, networking, security, and agent safety, are exactly what employers in IT and security are hiring for.
Project home: github.com/NousResearch/hermes-agent. Full docs: hermes-agent.nousresearch.com/docs.