Deploy Your Own Personal Hermes Agent
A private AI agent you can reach from Telegram. Install it once, connect a model and Telegram, then mostly just message it like a colleague.
1. How Hermes actually works
Hermes is not just a chatbot. It is an agent: a program that can reason, use tools, remember key facts, run scheduled work, and talk to you through messaging platforms like Telegram. It can also connect to services such as Google Workspace when you explicitly set that up.
The agent runs the reasoning, memory, skills, and tools. Telegram is just the chat window.
The agent identity, personality, and tone. It lives at ~/.hermes/SOUL.md, is auto-created on install, and is slot #1 of the system prompt. Rule: if it should follow the agent everywhere, it goes in SOUL.md.
A temporary mode overlay on top of SOUL.md. Examples: /personality concise, /personality technical, /personality teacher.
Two files in ~/.hermes/memories/: MEMORY.md for the agent’s notes about your environment, and USER.md for your profile and preferences. The agent manages these itself. You can simply say “remember that …”.
Optional project-specific instructions. Use it for a repository, app, or client project. This is different from SOUL.md, which is global personality.
Skills are reusable abilities in ~/.hermes/skills/ and can appear as slash commands. Tools include web search, browser use, image generation, text-to-speech, file work, and more through the Tool Gateway.
2. What you will set up
A small always-on computer, EU server, or local mini-PC.
The AI brain. It can be self-hosted, EU-hosted, or an API model.
Your private chat window to the agent.
3. Prepare your machine
Note: Prices and hardware notes are approximate — check current values before buying.
Use a dedicated always-on device. Do not run a business agent from a laptop that sleeps every night. Never paste real secrets into public examples; use placeholders only.
Option A — EU server
Best for most businesses. It is always online, cheap, and easy for OEJ or your operator to maintain. Pick an EU/EEA region during provisioning.
Option B — on-premises
Best when data should stay physically inside your office. Use a dedicated mini-PC and put both the router and the machine on a UPS battery backup.
Recommended EU server providers
For sensitive business data, choose data sovereignty, not just data residency. A US-owned cloud with EU servers can still be exposed to the US CLOUD Act. For sensitive client data, avoid AWS, DigitalOcean, Vultr, and Linode even if the region is EU.
Suggested server size for a Hermes agent using an API model: about 2 vCPU, 4 GB RAM, and 40 GB NVMe. Examples: Hetzner CX22/CAX11 class or UpCloud 2 GB+ class. The browser tool is happier with 4 GB+ RAM. Self-hosting a model on a rented server needs a GPU instance; see hardware tiers below.
Recommended hardware
Plain rule: if you use an API model, almost any small always-on machine works. If you self-host the model, the model must fit in the machine’s RAM or, on Apple Silicon, unified memory.
Most SMBs want this. Fanless Intel N100/N150 mini-PC, 8–16 GB RAM, 256 GB+ SSD, or base Mac mini M4 with 16 GB. About 10–30 W, quiet, cheap. Put it on a UPS with the router.
Mac mini M4 Pro with 48 GB unified memory, approximate $1,799 as of mid-2026; PC with NVIDIA 16–24 GB VRAM; or AMD Ryzen AI Max “Strix Halo” 128 GB mini-PC.
For 70B+ models: Mac Studio M-Max/Ultra with 96–128 GB, AMD 128 GB mini-PC, or multi-GPU workstation. More power, more heat, more noise.
Honest performance note: RAM or unified memory decides whether a local model runs. Memory bandwidth decides how fast. For API inference, neither matters much.
4. Data under your control
A good setup starts with one question: where does the data actually go? Hermes itself can run on your server, but the connected services matter. For example, a Google Workspace OAuth login gives the agent access to Gmail, Calendar, or Drive only within the permissions you approve. An AI model used through an API means the prompt and the needed task data are sent to that model provider. If you use OpenAI, Anthropic, Nous Portal, or another external API, data may leave the EU.
Practical rule: for sensitive work, prefer a self-hosted model or an EU-hosted model service. Use an API only when its data-handling terms fit the workflow. OpenRouter or another gateway is suitable for sensitive work only when you have explicit zero-data-retention terms and confirmation that prompts are not used for training. Give the agent only the OAuth scopes it needs and avoid unnecessary API connections.
5. One-time terminal setup
This is the only beginner terminal zone: install Hermes, connect a model, connect Telegram, make the gateway auto-start, and verify. After that, you mostly use Telegram.
Pick the one command for your operating system.
Linux, macOS, WSL2, or Android Termux:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashNative Windows PowerShell:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)Reload your Linux/macOS shell if needed:
source ~/.bashrcmacOS default shell:
source ~/.zshrcThe wizard asks four short things: provider, API key or OAuth login, model, and whether to enable tools / Tool Gateway.
Start the full setup wizard:
hermes setupTo add or change providers later:
hermes modelLowest-friction Nous Portal path:
hermes setup --portalSovereignty caveat: Nous Portal is convenient, but may route data outside the EU.
Create a bot with @BotFather. Send /newbot, choose a display name and a username ending in bot, then keep the token secret. Get your numeric Telegram user ID from @userinfobot. Paste the bot token and your numeric user ID when Hermes asks.
The gateway denies everyone unless they are allowlisted. If a bot token leaks, revoke it in BotFather with /revoke.
The gateway is the Telegram connection itself, so this part cannot be done by asking the agent in Telegram yet. Do it once so Hermes restarts with the computer.
Linux server recommended system service:
sudo hermes gateway install --systemPer-user Linux/macOS alternative:
hermes gateway installLinux per-user services may also need linger enabled:
sudo loginctl enable-linger $USERNative Windows uses Scheduled Tasks through hermes gateway install. WSL2 can use tmux or Windows Task Scheduler; see appendix.
Check the install, check the gateway, then message the bot from Telegram.
Run diagnostics:
hermes doctorCheck gateway status:
hermes gateway statusOptional direct Telegram test:
hermes send --to telegram "Hermes test message from the server."That is all the terminal work for the beginner path.
6. Now just talk to your agent
This is the main point. Once the gateway is running, most useful setup happens by messaging the bot in Telegram. The same style of commands also works from the CLI if an operator prefers it.
First things to try
Give it a name and personality
You can tell it in chat, use /personality, or edit ~/.hermes/SOUL.md.
Tiny SOUL.md example:
# Personality
You are Marta, a pragmatic operations assistant for a small Estonian business.
Be concise. Prefer clear next actions. Flag risks early.
Avoid hype and vague strategy.
It remembers you
Hermes manages memory itself. You do not need to edit memory files manually.
Set up a daily briefing
Ask it to watch itself
You can ask Hermes to create watchdogs and heartbeats. A watchdog is a small scheduled check that only messages you when something is wrong. A dead-man’s switch is an external uptime ping: if the ping stops, an outside service alerts you that the agent or server may be down.
Hermes can wire this through its native cron tool and script-only no-agent mode. The agent can watch your server, but restarting the gateway itself uses the operator script in the appendix, because a stopped gateway cannot restart itself.
Skills
Skills are reusable abilities. Run one with a slash command or ask the agent to learn a new one.
Connect Google Workspace
Google Workspace access gives the agent Gmail, Calendar, Drive, Sheets, Docs, and Contacts through OAuth2 with automatic token refresh. Tokens are stored under ~/.hermes/ on the agent machine as google_token.json.
Email only?
Use the simpler himalaya email skill. It works with a Gmail App Password and does not need a Google Cloud project. Create the App Password in Google Account → Security → App Passwords.
Calendar / Drive / Sheets / Docs?
Use the google-workspace skill. It needs a one-time Google Cloud OAuth client.
It should ask which services you need so it can guide the setup.
Enable the APIs you need in the API Library: Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API, and People API.
Go to Credentials → Create credentials → OAuth 2.0 Client ID → application type “Desktop app”. Download the client secret JSON.
If the OAuth app is still in Testing, add your Google account under Audience → Test users.
If the path starts with /, write it in a sentence so it is not mistaken for a slash command.
The agent gives you a link. Open it, sign in, approve access. The browser may redirect to a page that looks broken; that is expected. Copy the entire address-bar URL, or just the code, and paste it back to the agent.
After that, token refresh is automatic.
Example messages after Workspace is connected
Security and sovereignty note: Workspace access is powerful. Keep the bot allowlist to trusted people only. Protect the agent machine because the OAuth token lives there. Gmail, Calendar, and Drive data is processed by Google, a US company, so flag this for clients with strict data-sovereignty needs.
7. Appendix — Advanced / for operators
This section is not the beginner path. It is here for operators who want hand-written scripts, raw cron examples, and service details.
Gateway service details
User service:
hermes gateway installLinux system service:
sudo hermes gateway install --systemEnable user services after logout on Linux:
sudo loginctl enable-linger $USERWSL2 foreground run inside tmux:
tmux new -s hermes-gateway 'hermes gateway run'
Native script-only watchdog cron
Create a no-agent watchdog job:
hermes cron create "every 5m" --no-agent --script memory-watchdog.sh --deliver telegram --name "memory-watchdog"Script files must live in ~/.hermes/scripts/. Empty stdout means silent; non-zero exit or timeout sends an error alert.
Simple health-check script
Save as ~/.hermes/scripts/gateway-health.sh:
#!/usr/bin/env bash
set -euo pipefail
if ! hermes gateway status >/dev/null 2>&1; then
hermes gateway restart || true
hermes send --to telegram "Hermes gateway needed a restart on $(hostname)."
fi
Dead-man’s-switch ping script
Save as ~/.hermes/scripts/deadman-ping.sh:
#!/usr/bin/env bash
set -euo pipefail
curl -fsS "https://example.com/ping/YOUR_PLACEHOLDER_TOKEN" >/dev/nullUse your uptime service’s real ping URL privately. Never publish it in logs or docs.
Raw system cron examples
Operator-only crontab examples:
*/5 * * * * /home/hermes/.hermes/scripts/deadman-ping.sh
*/10 * * * * /home/hermes/.hermes/scripts/gateway-health.shPrefer Hermes native cron for agent-facing work. Use raw system cron only when an operator deliberately wants OS-level scheduling.
Updating & backups
hermes update keeps the agent current. Back up ~/.hermes/ — or use hermes backup — to preserve the whole agent: personality, memory, skills, and settings.
8. Troubleshooting
hermes not foundsource ~/.bashrchermes gateway statushermes model/cron list, then ask the agent to edit the job.9. Getting help
Contact OEJ OÜ if you want this deployed safely for your business. Before sending logs, remove secrets: API keys, bot tokens, OAuth URLs, IP addresses if sensitive, and customer data.
Disclaimer: This guide is provided for general informational purposes only. You follow these steps at your own discretion and risk. OEJ OÜ accepts no liability for any loss, damage, data loss, downtime, or costs arising from following this guide. Always keep your secrets private and back up your data. For a managed, supported deployment, contact OEJ OÜ.