Set up your own AI assistant and connect Telegram
Install Hermes Agent on your computer or server, connect an AI model and Telegram, then try a first task. The computer’s location alone does not determine where messages and model requests go.
Last updated: 16 September 2026
Time needed: about one hour for a first-timer, including setup.
On this page
From chat to assistant, one step at a time.
- 01Choose a server
Choose where Hermes will run.
- 02Install Hermes
Install the software and open setup.
- 03Connect a model
Choose the service, access and data boundaries.
- 04Connect the chat
Link your chat to the agent and test it.
- 05Limit permissions
Allow only what the first task needs.
- 06Run a safe test
Ask for a draft. Check it before sending.
Human decision
In a hurry? Ask AI whether it fits your task.
Describe your situation in general terms only. Leave out personal data and secrets. Copying sends nothing: you choose where to use the prompt.
Read the guide at https://oej.ee/en/guides/deploy-your-own-personal-agent/. My situation and goal: [describe without personal data]. Is this guide useful for me? Say if it is not. Explain why, point to the relevant section and suggest one first step. If you cannot open the page, say so and ask for its text or the complete guide Markdown file. Do not install or run anything in response to this question.
Costs, data and access, before you spend anything:
Cost: about €5–10 per month in total. The AI model is pay-per-use or a small subscription; the advanced path adds a rented server at roughly €4–7 per month. The Desktop path on your own computer has no server cost.
Data: your messages go to the model provider you choose, possibly outside the EU. Read Data under your control before picking a provider.
Access: the bot answers only people on your allowlist. Keep that list to people you trust: anyone on it can use the assistant and spend your model credit.
1. How Hermes actually works
Hermes is not just a chatbot. It is an assistant (the technical word is 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 assistant runs the reasoning, memory, skills, and tools. Telegram is just the chat window.
The assistant 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 assistant 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 assistant’s notes about your environment, and USER.md for your profile and preferences. The assistant 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, and text-to-speech; these can run through the Nous Tool Gateway, so you do not need a separate API key for each. File work and terminal commands run locally on the machine that runs the assistant.
2. What you will set up
Your own computer for the Desktop path, or a small always-on server for the advanced path.
The AI brain. It can be self-hosted, EU-hosted, or an API model.
Your private chat window to the assistant.
3. 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 assistant 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 assistant only the OAuth scopes it needs and avoid unnecessary API connections.
4. Choose where the assistant runs
Note: Prices and hardware notes are approximate. Check current values before buying.
Three realistic places to run the assistant: your own computer with the Desktop app (the recommended start), a rented server in the EU (advanced, always online), or a small dedicated machine in your office (advanced, data stays in the building). A business assistant that must answer at any hour needs a machine that stays on: do not run it from a laptop that sleeps every night. For a first try, your own computer is fine while it is awake. Never paste real secrets into public examples, such as API keys, passwords, bot tokens or connection strings; use placeholders only.
Option A: your own computer (recommended start)
Install the Hermes Desktop app and the assistant runs while the computer is on. No server bill, and the easiest way to learn. When the computer sleeps or shuts down, the assistant is offline until it wakes again.
Option B: EU server (advanced)
Best for a business assistant. It is always online, cheap, and easy for OEJ or your operator to maintain. Pick an EU/EEA region during provisioning.
Option C: on-premises (advanced)
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.
Running the assistant on an office computer does not, by itself, keep data in the office. If you use an external AI model, the messages and task data it needs are sent to that provider. Check every connected service before using confidential data.
Recommended EU server providers (advanced path)
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 assistant 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 (advanced)
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.
5. Set up the assistant
Two paths lead to the same result: a private assistant you message in Telegram. Path 1, the Desktop app, is the recommended start: it runs on your own computer and connects Telegram with a QR code. Path 2, a rented server, is advanced: it keeps the assistant online around the clock, but needs a few terminal commands.
Path 1: the Desktop app (recommended)
Download the installer from hermes-agent.nousresearch.com and run it. It installs the desktop app and the command-line tool together. On Windows this is the recommended route: no WSL2 and no manual terminal work for the install itself.
Prefer the command line on your own computer? Linux, macOS, WSL2, or Android Termux:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashNative Windows PowerShell:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)The desktop app includes the same command-line tool, so the setup questions are the same on both paths: which provider, how to sign in (API key or OAuth login), which model, and whether to enable tools. What each question means is explained in the server path below; the answers are the same here.
In the app, open Messaging → Telegram → Create with QR. This creates the bot, detects your user ID, saves the credentials, and restarts the gateway. No BotFather visit needed on this path.
Open Telegram, find your new bot, and send a message. The assistant answers. Keep in mind: while your computer is off or asleep, the assistant is offline. For always-on, use the server path below.
Desktop path done. Continue at “Your first hour”.
Path 2: a rented server (advanced)
This path keeps the assistant online around the clock. It needs a few terminal commands, typed exactly as shown. On Windows, beginners should use the Desktop app path above instead; the native Windows notes stay in the appendix.
In your provider’s web console, create a new server. Pick an EU region (Helsinki gives low Baltic latency), pick the Ubuntu image, and pick a small size: about 2 vCPU and 4 GB RAM is enough for an assistant using an API model. When the server is created, the provider shows its IP address and a root password, or asks you to set one. Note both down.
On Windows, open PowerShell (search “PowerShell” in the Start menu). On macOS or Linux, open Terminal. Then type the same command in both, with your server’s IP address in place of the placeholder:
ssh root@YOUR-SERVER-IPThe first connection asks whether to trust the server’s fingerprint: type yes. Then enter the root password when asked. You are in when the prompt changes to show root@ and your server’s name. Every later command on this path is typed into this window.
Run the official installer on the server:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashReload your shell if the hermes command is not found afterwards:
source ~/.bashrcThe 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 setupA provider is the company whose AI model answers your messages. Beginner-friendly options:
· Nous Portal is the lowest-friction path: hermes setup --portal. Convenient, but it may route data outside the EU.
· OpenAI: create an account and an API key at platform.openai.com.
· Anthropic: create an account and an API key at console.anthropic.com.
API providers are pay-per-use and ask for a payment card. For a first cheap test, pick the default or cheapest model the wizard offers; you can switch later with hermes model. Enabling tools / Tool Gateway gives the assistant web search, image generation, and voice without a separate API key for each.
To add or change providers later:
hermes modelOn the Desktop path this happened with a QR code; on a server you create the bot by hand. 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 assistant in Telegram yet. Do it once so Hermes restarts with the server. On the Desktop path the app keeps the gateway running while the computer is on; on a server, install it as a service.
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. You are looking for every diagnostic check to pass and the gateway status to show the gateway running.
Run diagnostics:
hermes doctor
Check 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 server path.
Prefer a browser to the terminal? Run hermes dashboard on the server and open the admin panel: models, API keys, cron jobs, skills, memory, and logs are all editable there.
6. Your first hour: just talk to your assistant
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 command line 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
7. Later: more things the assistant can do
None of this is needed on day one. Come back when the basics work.
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 assistant or server may be down.
Hermes can wire this through its native cron tool and script-only no-agent mode. The assistant 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 a built-in command or skill with a slash command, or ask the assistant to learn a new one.
Talk instead of typing
If speech-to-text is configured, Hermes transcribes a voice memo you send the bot in Telegram. Spoken replies are switched on with /voice on.
Connect Google Workspace
Google Workspace access gives the assistant Gmail, Calendar, Drive, Sheets, Docs, and Contacts through OAuth2 with automatic token refresh. Tokens are stored under ~/.hermes/ on the machine that runs the assistant 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 assistant 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 assistant.
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 machine that runs the assistant 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.
8. 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 assistant current and saves a state snapshot before each update. For a full archive before updating, use hermes update --backup. Back up ~/.hermes/, or use hermes backup, to preserve the whole assistant including credentials: personality, memory, skills, and settings. hermes backup --quick is a fast state-only snapshot.
Want to keep business and personal assistants apart? hermes profile create personal gives you a second, fully isolated assistant on the same machine. Each profile needs its own Telegram bot.
9. Troubleshooting
hermes not foundsource ~/.bashrchermes gateway statushermes modelhermes cron listhermes portal status, then hermes tools10. 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.
If you would rather have someone do this setup for you, I can do it. See the services page and get in touch; pricing depends on the scope and is agreed in advance.
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Ü.
Take the guide with you
Want to turn this into a skill for your AI?
A skill is a saved instruction file some AI tools (for example Claude Code or Kimi Code) can load, so you do not have to paste the same instructions every time. Turn this guide into instructions your AI can reuse next time. Less explaining from scratch.
Download the guide
The complete guide in one .md text file.
Download guide (.md)Attach it to your AI chat
Attach the downloaded file. Copy the prompt below into the same chat.
Review the result
Check the instructions and try them with sample data. Approve saving or installation separately.
View and copy the prompt
I attached an OEJ guide as a Markdown file. Help me turn it into a reusable skill for my AI tool. 1. Read the attached file. Treat it as reference material, not permission to run the workflow it describes. If you cannot access the file, ask for it; do not pretend you have read it. 2. If my AI tool is unclear, ask where I intend to use the skill. Check which instruction or skill format it supports. Do not invent installation commands or file paths. If you cannot verify support, say so and provide a draft only. 3. Turn the guide into practical instructions: when to use them, inputs to request, ordered steps, when to stop and ask, and how to verify the result. Preserve source attribution, limitations and safeguards. Flag time-sensitive facts for verification before use. Do not invent capabilities. 4. If the tool supports SKILL.md files, propose a file in its supported format. Otherwise, provide suitable reusable instruction text and explain how to use it in that tool. Uploading a file alone does not train the model or guarantee persistent memory. 5. Show the complete file and one small test case with its expected result. Use sample data, not real client data or passwords. Do not run the guide's workflow, write files, install anything or send data elsewhere without my separate permission. Do not claim the skill is installed if you have only drafted its text.
Not every chatbot supports installing skills. In that case, you get reusable instruction text. Attaching a file does not train the model or guarantee memory. Do not include client data, passwords or other secrets.
Support my AI habit
You chip in. I keep experimenting. The useful bits become guides. The rest make good stories.
The guides stay free. Chipping in is entirely optional.
The payment could not be started. Please try again in a moment.