Telegram Managed Bot Factory

A self-hosted MCP control plane that turns one user-owned Telegram manager bot into isolated, useful child bots. Ask Hermes for a supported bot, confirm that specific creation in Telegram, and the persistent Factory worker retrieves and contains the child credential without exposing it to the model or MCP.

Public alpha 0.1.2 is published on PyPI. Each PyPI version is immutable; install the current release below.

Install

Requires Linux with systemd --user, Python 3.11–3.14, uv, Hermes 0.18, and a separate Telegram bot with Bot Management Mode enabled.

uvx --from telegram-managed-bot-factory==0.1.2 bot-factory install-hermes

The local installer securely prompts once for the manager credential, enrolls the owner, installs the persistent user service, registers the six-tool stdio server with Hermes, and verifies discovery. It creates no child bot.

How it works

You → Hermes → Factory MCP ──durable request──▶ persistent worker
                  ▲                                │
                  │ safe status                    │ Bot API
                  │                                ▼
                  └──── Telegram confirmation ◀─ manager bot
                                                   │ child credential
                                                   ▼
                                         isolated child runtime

Hermes and MCP are the non-secret control plane. The persistent worker alone polls the manager bot and retrieves credentials. Each child receives only its own credential and uses instance-local state.

Useful profiles

Profile	Use it for
`quick_faq`	A public menu of 3–8 local plain-text answers and contact text.
`lead_inbox`	A privacy-noticed message form with owner notification and confirmed export/purge.
`link_inbox`	Owner-only URLs and notes with `/list` and `/done`; URLs are never fetched.

owner_echo is also included as an owner-only isolation and health smoke test. Profiles cannot provide arbitrary code, executables, filesystem paths, HTML, agent tools, or remote fetches.

60–90 second demo

After installation, ask Hermes:

Create a quick FAQ bot named “Studio FAQ” with username studio_faq_bot. Welcome: “Choose a question.” Add pricing, turnaround, and contact FAQs.

Hermes returns the Telegram creation link. Open it, approve once, then open the new child and send /start, /faq 1, and /health. If provisioning is still in progress, ask Hermes for the request status. For the other profiles, submit one test lead and try owner-only /export confirm then /purge confirm, or save a URL in link_inbox, inspect /list, and use /done 1.

Platform and boundaries

Supported runtime: Linux with systemd --user; Ubuntu and WSL2 are tested.
Supported clients: Hermes 0.18 legacy stdio and tested MCP 2026-07-28 paths.
Not supported: Windows/macOS installation, hosted multi-tenancy, arbitrary child code, automatic bot-account deletion, or bypassing Telegram approval.
The manager bot is user-owned and separate from the Hermes gateway bot.
Every child creation requires Telegram confirmation; this is not “one-click.”
The Official MCP Registry listing is metadata, not a security certification.

Security highlights

Tokens never enter MCP arguments/results, chat, CLI arguments, YAML, SQLite, manifests, logs, traces, fixtures, or Git.
Secret directories are 0700, files are 0600, and child credentials travel through an inherited anonymous file descriptor rather than argv or environment.
Child inbound update IDs and offsets are durable. Completed collisions are no-ops; a crash-ambiguous side effect is quarantined for reconciliation, not silently retried. External effects are not claimed to be exactly once.
Inputs are bounded and validated; profiles cannot execute or fetch supplied content.

See the security policy and architecture for the full boundary model.

Documentation and source

Source and issues
Specification · acceptance · status · publication evidence
Changelog · contributing · security
Telegram Managed Bots · Official MCP Registry entry

Troubleshooting and removal

Check the worker and Hermes registration without sharing unreviewed journal output:

systemctl --user status bot-factory-manager.service
hermes mcp test bot-factory

On WSL2, PID 1 must be systemd, and the distribution must remain running. Uninstalling the service/package does not delete Factory data or revoke Telegram bots; review local XDG bot-factory directories and BotFather controls separately.

telegram-managed-bot-factory

Install to Claude Code

README