Hermes Agent by Mega-Evolutions

Hermes Agent by Mega-Evolutions

Runs the Hermes Agent gateway in a Docker Space and connects it to Telegram through two bots, using the Telethon plugin alongside the python-telegram-bot transport.

Made by Mega-Evolutions on Hugging Face. These notes are Mindket's, written from its Space page and README; the app's own files and license are on Hugging Face.

About

What it is: This Space runs the Hermes Agent gateway inside a Docker container. It adds the Telethon Telegram platform plugin as a second transport that works in parallel with PTB, so two Telegram bots on separate tokens run side by side. It needs persistent storage, or the saved sessions are lost on restart.

Who it suits: People who want a Telegram-connected agent hosted on Hugging Face and are comfortable setting secrets and storage.

Industry | Who uses it | How they use it | Example
Software | Developers of chat agents | Host an agent that answers through Telegram | Deploy the Space and message the bot
Operations | Small teams | Keep an agent reachable in a Telegram channel | Set a home channel for the agent
Research | Agent builders | Compare two Telegram transports in one deployment | Run the PTB and Telethon bots in parallel
Self-hosting | Hobbyists | Run a personal agent without their own server | Add the secrets and start the container

People who want a one-click assistant with no setup can skip it, since it needs two bots and several secrets.

Where to use it:

• A Hugging Face Space with Docker and persistent storage
• Telegram, through the two bots you create
• Windows, macOS or Linux with Docker, for a copy on your own computer

Use case | Who | What they get back
Chat with the agent | Owners | Agent replies in Telegram
Run two transports | Developers | PTB and Telethon bots working in parallel
Keep sessions | Operators | A saved state that survives restarts

How to set it up:

• Docker on Windows, macOS or Linux, or a Hugging Face Space
• A bot token for the PTB bot from BotFather
• A second bot token for the Telethon bot, from a different bot
• A Telegram API ID and API hash from Telegram's developer site
• Your Telegram user ID and a home channel ID
• Persistent storage mounted at /data

1. Add the secrets as Space secrets, not variables.
2. Enable persistent storage at /data.
3. Deploy and wait for the Docker build to finish.
4. Both bots run in parallel on their separate tokens.

pip install -U huggingface_hub
hf download Mega-Evolutions/Hermes-Agent --repo-type space --local-dir Hermes-Agent
cd Hermes-Agent
docker build -t hermes-agent .
docker run -it -p 7860:7860 hermes-agent

How to use it: Once the Space is running, message the bot you created in Telegram. The source lists secrets only for a Space, so a local run would need the same values and the source does not show how to pass them.

Secret | What it holds
TELEGRAM_BOT_TOKEN | The token of the PTB bot
TELETHON_BOT_TOKEN | The token of the separate Telethon bot
TELETHON_API_ID | The API ID from Telegram's developer site
TELETHON_API_HASH | The API hash from Telegram's developer site
TELETHON_ALLOWED_USERS | Your Telegram user ID
TELETHON_HOME_CHANNEL | Your home channel ID
TELETHON_PROXY | Optional SOCKS5 proxy details for blocked mtproto

Example: You deploy the Space with both bot tokens and your user ID. You then send a message to the Telethon bot in Telegram, and the Hermes agent answers through it.

For newcomers and experts: If you are new, create two bots with BotFather first and keep their tokens ready. Then add every secret in the table before you deploy, since the bots will not start without them.

If you know the field, the gateway uses two Telegram transports at once, PTB and Telethon, each with its own token. The repository has hf_persist.py and a 00-hf-restore script for saving state, a main.sh entry script and a plugins folder. Without persistent storage at /data, state.db and every session disappear on restart.

You add secrets and storage
The Docker image builds
The gateway starts both transports
You message a bot in Telegram
The agent replies through it

Good to know:

• Storage: mount persistent storage at /data, because without it the state.db file and your sessions vanish at each restart
• Secrets: enter them as secrets and not as variables
• Proxy: a SOCKS5 proxy is optional when mtproto is blocked
• License: mit
• Cost to run: two Telegram bot tokens, a Telegram API ID and hash, and persistent storage
• Data it reaches: your Telegram bots and channel, and the sessions saved in state.db under /data

On Hugging Face, 13 November 2026

• Likes: 3
• Built with: docker
• License: mit

Links

• Space: https://huggingface.co/spaces/Mega-Evolutions/Hermes-Agent
• Files: https://huggingface.co/spaces/Mega-Evolutions/Hermes-Agent/tree/main

Try it

Open the Space in your browser, or copy it to your own Hugging Face account from its page. Nothing in this kit runs by itself.