Local AI Agent in Telegram: Connecting Hermes to Ollama

This guide shows how to run a local AI agent on Windows, use Ollama as its local model provider, and control it from your phone through Telegram. The important security boundary is a Telegram user-ID allowlist: the bot can receive messages from the internet, but only approved IDs may receive an answer or trigger Hermes.
The commands below are a reproducible setup outline based on the documented Hermes gateway configuration and Ollama’s local HTTP endpoint. They have not been executed in this article’s workspace. Replace every placeholder, and treat the verification section as a checklist to run on your own Windows machine.
What you are building
The finished path is:
Phone
│ Telegram message
▼
Telegram Bot API
│
▼
Hermes gateway on Windows
│ approved user ID only
▼
Ollama at http://127.0.0.1:11434
│
▼
Local model
Ollama serves the model locally. Hermes Agent handles the conversation and gateway. Telegram is only the remote control channel; it does not make Ollama publicly reachable.
Prerequisites
- Windows with PowerShell available.
- Ollama installed and able to run a model locally.
- Hermes Agent installed according to its current Windows instructions.
- A Telegram account and a bot token created with BotFather.
- A model compatible with the tool-calling behavior you expect from Hermes. A chat-only model may answer questions but may not reliably perform agent actions.
You do not need to expose port 11434 to the internet. Keep Ollama bound to its local address unless you have a separate, authenticated network design.
1. Install and check Ollama
Install Ollama from its official Windows distribution, then open PowerShell. Check that the command is available:
ollama --version
Pull a model that your computer can handle. The model name below is an example; choose a model that is available in your Ollama installation and suitable for your hardware:
ollama pull gemma4:31b
For a smaller computer, use a smaller model from the Ollama library. The trade-off is usually lower latency and memory use versus weaker reasoning or tool use. Do not assume that a model supports agent tools merely because it can produce normal chat replies.
Check the installed models:
ollama list
Check the local API from PowerShell:
Invoke-RestMethod `
-Method Get `
-Uri "http://127.0.0.1:11434/api/tags"
A successful response should be JSON describing installed models. This is a local connectivity check, not a test of Hermes.
2. Create the Telegram bot
In Telegram, open the verified BotFather account and create a new bot. Telegram will display a bot token. Store it as a secret. Do not paste it into this article, a public repository, a screenshot, or a chat message.
Use a temporary PowerShell variable while configuring the session:
$telegramToken = "PASTE_YOUR_BOT_TOKEN_HERE"
Check that the token identifies the expected bot:
Invoke-RestMethod `
-Method Get `
-Uri "https://api.telegram.org/bot$telegramToken/getMe"
If the response is unsuccessful, stop and create a new token with BotFather. A bot token grants control over the bot and must be rotated if it is exposed.
3. Find your Telegram user ID
The bot needs your numeric Telegram user ID, not your username. One practical method is to send a private message to the bot and inspect the update returned by Telegram:
Invoke-RestMethod `
-Method Get `
-Uri "https://api.telegram.org/bot$telegramToken/getUpdates"
Look for a structure similar to:
result[0].message.from.id
Copy only the numeric ID into your private configuration. Do not publish it together with your bot token. If result is empty, send another message and repeat the request.
For a real deployment, use a small script or a controlled log review to extract the ID rather than pasting full Telegram updates into a public issue. Telegram updates can contain message text and personal metadata.
4. Configure Hermes to use Ollama
Hermes supports an OpenAI-compatible local endpoint for Ollama. The relevant configuration shape is:
model:
default: "YOUR_OLLAMA_MODEL"
provider: "custom"
base_url: "http://127.0.0.1:11434/v1"
platforms:
telegram:
enabled: true
token: "YOUR_TELEGRAM_BOT_TOKEN"
Replace YOUR_OLLAMA_MODEL with the exact name shown by ollama list. Replace the token placeholder with the bot token, but keep the configuration file private and restrict its filesystem permissions where practical.
The exact configuration location can vary by Hermes release and installation method. Use the configuration file shown by your installed Hermes setup command or documentation. Do not create multiple competing configuration files without checking which one the gateway reads.
5. Restrict access by Telegram user ID
Enable Hermes’s Telegram gateway only after confirming how the installed version expresses its allowlist. The option name may differ between releases. The security requirement is stable: configure an allowlist containing your numeric Telegram user ID, and make the gateway reject every other user.
A conceptual example looks like this:
platforms:
telegram:
enabled: true
token: "YOUR_TELEGRAM_BOT_TOKEN"
allowed_user_ids:
- 123456789
This field name is an example until confirmed against your installed Hermes version. If your version does not document allowed_user_ids, do not guess a replacement and assume it works. Find the version-specific Telegram security setting, or place a small authenticated proxy in front of the gateway that filters Telegram updates by message.from.id.
Do not rely on any of these as your only access control:
- Hiding the bot username.
- Disabling group privacy while leaving the bot in groups.
- Checking a Telegram username instead of the immutable numeric user ID.
- Assuming that a private chat means only you can use the bot.
- Putting the bot token in a frontend, batch file committed to Git, or public configuration.
6. Start the gateway
With Ollama running and the configuration saved, start the Hermes gateway from the Hermes installation environment:
hermes gateway
Keep this PowerShell window open during the first test. The startup output should identify the Telegram gateway and the configured model provider. It should not show a cloud provider or a missing-token fallback unless you intentionally configured one.
Now send a private message to the bot from the approved Telegram account:
/start
What local model are you using?
The answer should come through the Telegram bot. The gateway log should show a received update and a response without exposing the bot token.
7. Verify the security boundary
Test both the positive and negative paths. The following results are expected behaviors to verify; they are not test results performed for this article.
| Test | Expected behavior |
|---|---|
| Approved user sends a normal message | Hermes processes it and Telegram receives a reply. |
| Unapproved user sends a normal message | The message is ignored or rejected before reaching the agent. |
| Ollama is stopped | Hermes reports a provider connection failure; it must not silently switch to a cloud provider unless configured to do so. |
| Gateway is stopped | No new Telegram reply is produced by the local machine. |
| Bot token is rotated | The old token no longer authenticates API requests. |
For the unapproved-user test, use a second Telegram account only if you control it and can do so without disclosing either account’s personal data. Never ask a stranger to test your bot.
Useful commands
These commands help distinguish the most common layers of failure:
# Confirm Ollama is installed
ollama --version
# List local models
ollama list
# Show currently loaded models
ollama ps
# Check the Ollama model API
Invoke-RestMethod `
-Method Get `
-Uri "http://127.0.0.1:11434/api/tags"
# Check that Telegram accepts the bot token
Invoke-RestMethod `
-Method Get `
-Uri "https://api.telegram.org/bot$telegramToken/getMe"
# Start Hermes
hermes gateway
Failure cases
Hermes cannot connect to Ollama
First check that Ollama is running and that the endpoint is exactly http://127.0.0.1:11434/v1 for the OpenAI-compatible provider configuration. Then compare the configured model name with ollama list. A typo in the model tag is enough to produce a provider error.
The bot receives messages but does not answer
Check the gateway console, the bot token, and whether another process is consuming Telegram updates. Do not run two long-polling gateways with the same bot token during diagnosis. If a webhook was previously configured, remove or reconfigure it according to the Telegram Bot API behavior for your deployment.
The model answers but does not perform actions
This may be a model capability issue rather than a Telegram issue. Confirm that the selected model supports the tool-calling behavior Hermes expects. Also check whether Hermes tools are enabled and whether the local execution backend has permission to perform the requested action.
Responses are slow or Windows becomes unresponsive
Local inference can consume substantial RAM, GPU memory, CPU time, and disk space. Try a smaller model, reduce concurrent workloads, or stop other GPU-heavy applications. A slow first response does not by itself indicate a Telegram or gateway failure.
Everyone can use the bot
Stop the gateway immediately, inspect the active configuration, and confirm the allowlist is actually loaded by the installed Hermes version. A configuration key that is merely plausible is not evidence that access control is active. Test with a second controlled account before putting the bot into regular use.
Operational limits
- Telegram is an external service. Messages travel through Telegram even when model inference remains local.
- Local inference does not make agent actions safe. File deletion, shell commands, browser actions, and network access depend on Hermes tools and permissions.
- An allowlist protects the Telegram entry point, not a compromised Windows account or a leaked bot token.
- Ollama being bound to localhost protects it from direct remote access, but other software running on the same Windows account may still reach it.
- Model quality, tool use, latency, and memory requirements depend on the exact model and Hermes release.
- Configuration names can change. Confirm security-related options against the documentation shipped with the version you install.
Final checklist
- Ollama responds on
127.0.0.1:11434. - The selected model appears in
ollama list. - The Telegram token is private and validated with
getMe. - Your numeric Telegram user ID is recorded privately.
- The Hermes gateway is configured for the local Ollama-compatible endpoint.
- The gateway’s user-ID allowlist is confirmed for the installed version.
- An approved-user message succeeds.
- An unapproved-user message is ignored or rejected.
- Ollama, Hermes, and Telegram failures are distinguishable in the logs.
Once those checks pass on your own machine, you have a Telegram control surface for a local Hermes agent without exposing the Ollama API directly to the internet. Keep the bot private, review tool permissions regularly, and rotate the token if there is any doubt that it was exposed.
Continue with the Agent Lab Journal guides or look up unfamiliar terms in the glossary.