25 min read Updated 18 November 2026 Beginner

Local AI Agent in Telegram: Connecting Hermes to Ollama

Локальный AI-агент в Telegram: подключаем Hermes к Ollama
Temporary fallback cover; replace in editorial pass.

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

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:

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

Final checklist

  1. Ollama responds on 127.0.0.1:11434.
  2. The selected model appears in ollama list.
  3. The Telegram token is private and validated with getMe.
  4. Your numeric Telegram user ID is recorded privately.
  5. The Hermes gateway is configured for the local Ollama-compatible endpoint.
  6. The gateway’s user-ID allowlist is confirmed for the installed version.
  7. An approved-user message succeeds.
  8. An unapproved-user message is ignored or rejected.
  9. 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.

We publish what works for us—and implement the same solutions for your business. We design AI automation, Telegram bots, chats, and AI agents for real-world processes. Discuss your project →