Uroboros

Modular Telegram userbot on Python and Telethon.
One-command modules, inline buttons and forms, account protection from malicious code.

📚 Docs · 🚀 Install · ⌨️ Commands · 🧩 Write modules · 📦 Modules · 🇷🇺 Русский

✨ Features

🚀 Install

Linux, VPS, Termux, macOS:

curl -fsSL https://raw.githubusercontent.com/asykixd/uroboros/master/install.sh | sh

Or pip install uroboros-userbot. Docker, systemd, Termux autostart and Windows: see install docs.

On first run Uroboros prints a link to a web login panel: enter api_id/api_hash from my.telegram.org/apps, phone, code and 2FA password, or scan a QR code. The panel shuts down after login, and Uroboros creates its inline bot via @BotFather. Console login: --cli.

⌨️ Main commands

Full list with access levels: command reference.

🧩 Write a module

# meta developer: @you
# meta permissions: none
# requires_uroboros: 1.0
from uroboros import Module, command, utils


class Notes(Module):
    """Notes"""

    @command("save", emoji="💾")
    async def save(self, message):
        """<name> <text> — save a note"""
        name, _, text = utils.get_args_raw(message).partition(" ")
        self.set(name, text)
        await utils.answer(
            message,
            utils.card(
                "✅ <b>Note saved</b>",
                [f"🏷 Name: <code>{utils.escape_html(name)}</code>", f"📏 Length: <code>{len(text)}</code>"],
                hint=f"show: <code>.note {utils.escape_html(name)}</code>",
            ),
        )

Modules get self.client (Telethon), storage (self.get/self.set), self.config, command filters, watchers, @loop tasks, libraries, inline forms (self.inline.form(...)) and utils helpers. See the module guide; ready-made modules and a repo template: uroboros-modules.

🛡 Security

Third-party modules run in the bot's process. Uroboros scans their code on install, shows permissions and diffs, pins GitHub modules to a commit and blocks access to the session. It is not a sandbox: install modules you trust. See security.

🛠 Development

dev is the development branch (X.Y.Z-dev), master is stable.

python3 -m venv .venv && .venv/bin/pip install -e '.[dev,docs]'
.venv/bin/python -m pytest
.venv/bin/mkdocs serve

🙏 Credits

The module API and adapter follow Hikka (AGPL-3.0); thanks to its authors. Built on Telethon and aiogram.

📄 License

AGPL-3.0, see LICENSE. Contributing · Security policy