This is the guide I wish existed when “agent” still sounded like another word for chatbot. It explains the public, reproducible parts of the setup without publishing private infrastructure, credentials, client data, personal prompts, or the details of any live system.
§1What Hermes Agent actually is
Hermes Agent is an open-source agent runtime built by Nous Research. It is not a single model and it is not merely a Telegram bot. It is the layer that keeps a conversation alive, chooses a configured model, gives that model tools, stores session context, runs skills, schedules jobs, handles files and voice, and returns the result through whichever interface you use.
The distinction matters. A model can write an answer; an agent can inspect a folder, search the web, run a test, create a document, remember the session, pause for approval, and send the finished artifact back. Hermes provides the machinery around the model that makes those actions coherent.
- 01You askText, voice, image, or file arrives from Telegram.
- 02Gateway receivesThe right chat, user, and session are resolved.
- 03Hermes plansContext, skills, tools, and permissions shape the task.
- 04Model reasonsYour selected provider supplies the reasoning engine.
- 05Tools actHermes reads, computes, searches, or prepares a bounded change.
- 06Result returnsThe answer or generated file arrives in the same chat.
Telegram is the keyboard. OpenRouter is the engine bay. Hermes is the operating system between them. Changing the model changes the engine, not the assistant’s entire identity or tool setup.
§2What you need before starting
- A supported host. The official installer supports Linux, macOS, WSL2, and Termux. Use a machine that can stay on if you want an always-available assistant.
- One model provider. This guide uses OpenRouter because one API gives you access to many model families. Hermes supports other providers too.
- A Telegram account. You will create a separate bot through Telegram’s official @BotFather account.
- A small security boundary. Decide which operating-system user, working directory, tools, and folders the agent is allowed to reach before connecting chat.
- Comfort with a terminal. You do not need to be a systems engineer, but you should be able to paste a command, read an error, and keep a secret out of screenshots.
§3Install Hermes and prove the terminal path first
Run the official installer
On Linux, macOS, WSL2, or Termux, the current official quick-install command is:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashIf piping a remote script directly into a shell is outside your risk tolerance, download and inspect the installer before running it. Use the official quickstart as the source of truth because installation details can change.
Configure a model provider
Run the interactive provider picker:
hermes modelSelect OpenRouter, enter the API key when prompted, and select an initial model. Hermes stores secrets in its private configuration area—never paste the key into a public repository, prompt template, screenshot, or Telegram message.
Test locally before adding Telegram
Start Hermes in the terminal and ask a harmless question. Then inspect the available tools and confirm that the working directory is the one you intended.
hermes
hermes toolsDo not connect a remote chat surface until the local path can authenticate to the intended provider and complete a simple turn. This isolates model setup from Telegram setup.
§4Use OpenRouter as the model switchboard
OpenRouter exposes many models through one compatible API. For a personal assistant, that means you can use a fast inexpensive model for routine sorting, a stronger reasoning model for planning, a vision model for images, or an automatic router—without reinstalling Hermes.
Inbox and routine work
Classification, short summaries, formatting, reminders, and low-risk repetitive tasks.
Everyday assistant
Writing, research synthesis, planning, files, and most multi-step requests.
Complex reasoning
Architecture, difficult debugging, long comparisons, and consequential analysis.
Images and documents
Screenshots, diagrams, scanned material, and visual QA when the selected model supports it.
Let the router choose
OpenRouter’s auto router can select a model from the allowed set based on the request.
Switch models from Telegram
Inside a Hermes messaging session, use /model to see or change the active model. The official command accepts provider:model syntax:
/model
/model openrouter:openrouter/auto
/model openrouter:anthropic/claude-sonnet-4.5Those identifiers illustrate the syntax, not a permanent recommendation. Model catalogs, names, prices, context windows, and availability change. Check the live OpenRouter catalog before standardizing a model, and verify the active model with /status after switching.
| Question | Why it matters | Practical default |
|---|---|---|
| How sensitive is the task? | Prompts and attachments leave your host when using a cloud provider. | Keep secrets and regulated data out; use a local endpoint when that boundary matters. |
| Does it need tools? | Not every model behaves equally well with multi-step tool use. | Test with the actual Hermes workflow, not a chat benchmark. |
| How expensive can it be? | Long sessions, files, and tool loops can consume more tokens than a single chat. | Set an OpenRouter budget and use a cheaper model for routine work. |
| Does it need vision? | Text-only models cannot inspect screenshots or images. | Choose a vision-capable model only for sessions that need it. |
| Do you need consistency? | Automatic routing can change the underlying model between tasks. | Pin a specific model for repeatable workflows; use auto for general requests. |
§5Connect Hermes to a private Telegram bot
Create the bot with @BotFather
- Open Telegram and message the official @BotFather account.
- Send
/newbot. - Choose a display name.
- Choose a unique username ending in
bot. - Copy the API token into your password manager or directly into the Hermes setup prompt.
The token controls the bot. If it appears in a screenshot, log, public repository, or shared chat, use BotFather’s /revoke command immediately and replace it.
Find your numeric Telegram user ID
Hermes authorizes numeric user IDs, not usernames. The official guide recommends messaging @userinfobot or @get_id_bot and saving the number returned.
Run the gateway wizard
hermes gateway setupSelect Telegram, enter the bot token, and add your numeric user ID to the allowlist. The equivalent manual environment fields are TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS, but the wizard is the safer beginner path.
Start and verify the gateway
hermes gatewayOpen the bot in Telegram and send a simple message. Then run these checks inside the chat:
/whoami
/status
/help/whoami shows your access tier and scope. /status confirms session and model state. If the bot does not respond, check the gateway terminal before changing anything else.
Keep it running after logout or reboot
On a laptop or development box, install the default user service. On a headless Linux server, the official guide supports either a user service with lingering or a boot-time system service.
hermes gateway install
hermes gateway start
hermes gateway statusUse only one service mode for an installation. Running both user and system gateway units creates ambiguous start, stop, and status behavior.
Telegram privacy mode is enabled by default. In groups, the bot normally sees commands, replies to itself, and certain service messages—not every conversation. If you disable privacy mode through BotFather, remove and re-add the bot to the group so Telegram refreshes that state. For a personal assistant, start with a private direct message and an explicit allowlist.
§6What a personal Hermes assistant can do
Ask and orient
Summarize a maintained knowledge folder, explain which document owns a decision, or identify the safest place to begin.
“Read the project notes and tell me what is current, stale, and still uncertain.”Research
Search, compare sources, preserve links, separate facts from inference, and return a concise brief.
“Research this topic from primary sources and give me a claim-by-claim source list.”Work with files
Read attachments, organize documents, produce Markdown, CSV, PDF, images, or code, and send supported files back through Telegram.
“Turn this document into a one-page checklist and send the file back.”Long-running work
Use a separate background session so your main conversation remains responsive while research, builds, or checks continue.
“/background Compare these sources and report when the table is ready.”Quiet monitoring
Run scheduled checks and deliver results to a chosen home channel. Good monitors report the difference between unchanged and unable to check.
“Notify me only when the observed state crosses this threshold.”Session continuity
Name, resume, compress, or reset sessions. Preserve durable decisions in files rather than assuming every chat turn will remain useful forever.
“Summarize what changed, the evidence, and the next safe action.”Voice and images
Send voice notes, screenshots, photos, and attachments when the configured speech and model providers support them.
“Transcribe this note, extract the actions, and ask before scheduling anything.”Action-capable workflows
Prepare a command, message, change, or release—but stop at the consequential boundary and show the final payload first.
“Prepare the change, run the checks, show me the diff, and wait.”Useful commands inside Telegram
/newStart a fresh conversation./modelShow or change the model./statusInspect the active session and runtime./whoamiSee your access tier and allowed commands./backgroundRun a separate task without blocking the main chat./stopStop the running agent./approveApprove a pending dangerous command./denyReject the pending command./sethomeChoose where scheduled results should arrive./compressCompress long conversation context./resumeResume a named session./helpShow available commands.§7Skills turn a general agent into your assistant
A model knows how to generate. A skill tells Hermes how a particular job should be done: what inputs are required, which tools are allowed, what evidence to collect, what output format to return, and where to stop.
Hermes can browse and install compatible skills:
hermes skills browse
hermes skills install openai/skills/k8sTreat community skills like software, not magic prompts. Read their instructions, inspect scripts, understand their tool access, pin important behavior in tests, and remove anything that asks for broader authority than the job requires.
What must be supplied?
Files, URLs, dates, exact scope, and the decision the output needs to support.
What may it touch?
Read-only sources, a specific folder, browser access, terminal commands, or a named external service.
What proves completion?
Exit codes, source links, checksums, screenshots, tests, or a live read-back from the destination.
Where must it pause?
Before sending, publishing, purchasing, deleting, granting access, or changing production.
What should survive the chat?
Stable preferences, decisions, runbooks, and exact failure lessons—never raw secrets or unnecessary personal detail.
§8Security: Telegram is the interface, not the boundary
A Hermes Telegram integration can expose terminal tools. That makes it dramatically more capable than a normal bot—and means the host, gateway configuration, and allowlist are the real security boundary.
Allowlist yourself
Keep TELEGRAM_ALLOWED_USERS narrow. Do not enable “allow all” on an agent with terminal access.
Run as a dedicated user
Give that account only the folders and commands required. A successful root test does not prove the runtime user can work safely.
Scope the working directory
The messaging gateway uses its configured terminal working directory. Do not point it at an entire home directory by accident.
Keep secrets off chat
Store tokens in Hermes’s private environment. Redact logs and screenshots. Rotate a bot or provider key immediately if exposed.
Retain approval gates
Read-only work can be autonomous. Messages, deployments, purchases, deletes, and permission changes should stop for confirmation.
Verify the active provider
After changing configuration, use the live session state—not an old file—to confirm the provider and model actually in use.
Separate public and private memory
Public-safe operating principles can be shared. Private paths, identities, client facts, tokens, and internal schedules should not be.
Update with rollback
Back up configuration, understand service mode, apply updates deliberately, and verify the gateway from the same runtime identity.
§9Troubleshooting by layer
| Symptom | Check first | Likely boundary |
|---|---|---|
| The bot is silent | Is hermes gateway running, and does its log show Telegram connected? | Gateway process, bot token, or network. |
| You are denied | Does /whoami work, and is your numeric ID in the allowlist? | Authorization, not model quality. |
| Direct messages work; groups do not | Check BotFather privacy mode, group membership, mention rules, and allowed chat IDs. | Telegram delivery and group policy. |
| The model errors | Run hermes model, confirm the API key and live model ID, then test locally. | Provider authentication or catalog drift. |
| The wrong model answers | Use /status after /model; inspect configured fallbacks. | Session override or fallback routing. |
| It stops after logout | Check hermes gateway status and the chosen service mode. | Service persistence, not Telegram. |
| A generated file cannot be sent | Can the gateway process read the final host path? | Container/host filesystem visibility. |
| A “success” changed nothing | Read the destination back from its authoritative source. | Downstream outcome verification. |
§10A sensible first-week routine
- DAY 1Terminal onlyInstall, choose one model, inspect tools, and complete harmless read-only tasks.
- DAY 2Private Telegram DMCreate the bot, allowlist one user, verify
/whoami,/status, and/stop. - DAY 3Model comparisonRun the same real task with a fast model, a balanced model, and a deeper model. Compare cost, tool reliability, and output—not vibes.
- DAY 4One bounded skillAdd a repeatable read-only workflow with an exact output and evidence requirement.
- DAY 5One background taskUse
/backgroundfor research or a safe local check while keeping the main chat responsive. - WEEKENDPersistence and recoveryInstall the gateway service, reboot once, confirm it returns, review logs, and document how to rotate both keys.
The shortest honest summary
- Hermes is the agent runtime; it is not the model.
- Telegram gives you a convenient private interface from any device.
- OpenRouter lets you change reasoning engines while preserving the same agent setup.
- Skills, sessions, tools, files, voice, background tasks, and scheduled work make it useful beyond chat.
- An allowlist, limited runtime user, scoped working directory, secret hygiene, and approval gates make it defensible.
§11Official sources and freshness
This guide was re-verified against current official documentation on 28 August 2026: the quick-install command above is unchanged and every linked page below resolves. Hermes is moving quickly; use these pages to verify commands and configuration before installing, and keep the agent itself current with hermes update.
- NousResearch/hermes-agent on GitHub — repository, installer, feature overview, and releases.
- Hermes Agent quickstart — current installation and first-session flow.
- Hermes Telegram guide — BotFather, allowlists, privacy mode, voice, files, groups, and service behavior.
- Hermes provider guide — OpenRouter and other model providers.
- OpenRouter quickstart — API keys, model identifiers, and compatible requests.
- OpenRouter Auto Router — automatic model selection and routing controls.
§12Quick answers
Do I need Telegram to use Hermes Agent?
No. Hermes runs in the terminal first, and this guide deliberately proves the local path before any chat surface. Telegram is an optional remote interface you add once the terminal session can authenticate and complete a simple turn.
What does it cost to run?
Hermes installs from the official public repository; the running cost is your model provider’s per-token usage behind the key you configure. Set a provider budget and route routine work to a cheaper model — long sessions, files, and tool loops consume more tokens than a single chat.
Which model should I start with?
Start with one balanced general model through OpenRouter, then switch by workload with /model: fast models for routine sorting, deeper models for planning, a vision-capable model for images, or the auto router. Verify the active model with /status after switching.
Is it safe to connect an AI agent to Telegram?
Treat Telegram as the interface, not the security boundary. Decide the operating-system user, working directory, tools, and reachable folders before connecting chat; restrict the bot to your own account ID; and keep secrets out of messages and screenshots.
Can Hermes run on a phone?
The official installer supports Termux on Android, so it can. An always-available assistant is better hosted on a machine that stays on — a Mac, a Linux box, or a small VPS — with the phone acting as the Telegram client.