Self-hosted service
TeamUltroid/Ultroid avatar
TeamUltroid/Ultroid

Ultroid: the install fetches an unpinned fork, and the required variable is a live session token

Advanced Multi-Featured Telegram UserBot, Built in Python Using Telethon lib.

2,983 stars8,013 forksPythonAGPL-3.0

At a glance

What is it?
A pluggable Telegram userbot and call-music bot built on Telethon, licensed AGPL-3.0, with five deployment manifests and a stable-sounding front page. Two things sit underneath the feature list. The requirements file installs a fork of the project's own core library from a third party's moving branch, and the single mandatory configuration value is an authenticated session token rather than a password. The newest release tag is from August 2022.
Who is it for?
Judge this on two questions before anything else. Does the account you would log in with matter more than the features, because a userbot acts as you rather than as a bot, and a session token does not expire the way a password does.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository last received commits 11 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • TeamUltroid/Ultroid2,983 ★ · +4
Star history
Repository2026-09-242026-11-14
TeamUltroid/Ultroid3k3k

4 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The requirements file installs a fork of its own core library

The dependency list is eleven lines, and one of them is not a package name. It is an archive address pointing at a fork of Telethon, on the main branch of a personal account:

code
# Important Requirements here.
telethon>=1.44.0
gitpython>=3.1.52
https://github.com/New-dev0/Telethon-Patch/archive/main.zip
python-decouple>=3.8
python-dotenv>=1.2.2
telegraph>=2.2.0
enhancer>=0.3.4
requests>=2.34.2
aiohttp>=3.14.1
catbox-uploader>=2.9
cloudscraper>=1.2.71

Every other line carries a version floor. That one carries no version and no integrity hash.

So installing the requirements fetches whatever that branch contains at that moment, into every user's environment. Three consequences, in increasing order of seriousness. The build is not reproducible, since two installs on different days can differ. A push to that branch changes what gets installed here without any change to this repository, which turns someone else's commit into a supply-chain event for everyone. And the fork is not the library named in the credits, so the code actually executing is a third party's modification of it rather than the upstream release.

The file's only annotation is a comment saying the requirements there are important, with nothing marking which of the eleven those are.

For a project that asks for an authenticated session on a personal account, this is the first thing to look at, and it has nothing to do with whether the bot works.

The one mandatory value is a session token, not a password

The only required configuration value is a session string for the account's own login session. Everything else is a database, a bot token, a log channel and a deployment token.

What that value is matters more than the variable name suggests. It is an authenticated session token. Whoever holds it does not need the phone, the password or the second factor again.

The page then lists five ways to obtain one, and the range is the finding. A hosted development workspace, three shell one-liners aimed at different operating systems, and a Telegram bot operated by someone else.

Producing one requires the account's own credentials at that moment. So generating it through a third party's bot or a hosted workspace means handing a live authenticated session to that party, and the token does not have the expiry or the rotation story a password has.

That is the substance of the safety question, and it is worth answering before any question about features.

The narrow advice follows directly. Generate the session locally, treat the resulting value as a password, and do not paste it into a web form or a chat. The project does ship a local script for exactly that, and it is the only route on the page that involves nobody else.

I am not reproducing the one-liners here. The point is not what they contain, it is which of the five put a third party in the path.

The Dockerfile builds from the project's own published image

The build file's first instruction is not a language runtime or a base distribution. It is this project's own published container image, on its floating main tag:

dockerfile
FROM theteamultroid/ultroid:main

# set timezone
ENV TZ=Asia/Kolkata
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

COPY installer.sh .

RUN bash installer.sh

# changing workdir
WORKDIR "/root/TeamUltroid"

# start the bot.
CMD ["bash", "startup"]

So this Dockerfile is not a reproducible build of the source tree. It is: take the image we published, and re-run the installer inside it. Two people building the same commit get whatever that tag pointed at when they built.

There is no unprivileged user, so the bot runs as root inside the container, in a working directory under root. The timezone is pinned to one region regardless of where the container actually runs, which affects log timestamps and anything scheduled.

The licence header carries a small typographical slip, capitalising the first letter of a word mid-sentence, and its two reference addresses are wrapped in angle brackets with spaces inside them, which will not resolve as links.

Put this beside the previous section and the picture is consistent: there are two independent places where what you get is decided by something other than the commit you checked out. One is a dependency branch and one is a base image tag.

Three lists of required variables, none matching

The sample environment file, the compose file and the documentation each name a different set of variables.

The sample has seven. The compose file passes ten through to the container. The documentation describes the session plus one of three database options, so it names eight.

The three present in the compose file and absent from the sample are a Mongo connection string, a SQL database URL, and a deployment-platform token.

So the path a new user actually walks is: copy the sample, fill it in, bring up the compose file, and get those three silently empty. Nothing warns them. The compose file's own comments claim those variables default to None, but an unset shell variable is passed through as an empty string, so the comment describes a behaviour the interpolation does not produce.

That deployment token has its own oddity. It belongs to one hosting platform's pipeline and has no business in a compose file a local user would run.

None of this is dangerous. All of it is the sort of drift that produces a support question, and it is a fair signal of how much attention the deployment files receive compared with the plugin surface.

One more detail in the compose file worth knowing: it declares no ports, no volumes and no restart policy, only a build and an environment block. For a client that dials outward and keeps a session alive that is arguably correct, and it does mean there is nothing there to persist.

The one-command installer runs a script from an opaque short link

The quick install, offered for three platforms, is a download of a Python file from a shortened address followed by executing it. The same short-link host is used for the session generator, and a separate short domain serves the mobile Linux installer.

Because the address is a generic short link, the page does not tell you which script you are about to run. You cannot read it before running it, and you cannot tell whether it changed since yesterday.

The traditional method sits further down the same page and is fully inspectable: clone the repository, create a virtual environment, install two requirements files, generate a session, and run a start script. Every step is a command whose contents you can open first.

The easy method saves a few keystrokes and removes the only opportunity to read what you are executing.

For a project whose audience is largely non-technical that is a defensible convenience, and it is also the largest single supply-chain surface in the repository, sitting directly in front of an install that already pulls mutable third-party code.

The middle path is obvious and unused: have the quick command fetch from a pinned commit in this repository instead of from a short link to somewhere else. Everything the convenience buys would survive.

Worth contrasting the two deployment halves. The getting-started route is friendly and opaque; the traditional route is tedious and inspectable. Nothing in the document tells you which one you are choosing when you copy the short one.

Five deployment manifests and one that points at nothing

The root carries a hosting manifest for one platform, an application descriptor for a second, a pipeline descriptor for a third, a container build file and a compose file. Plus two shell installers, one general and one for a mobile Linux environment.

The navigation offers three hosting targets and three local methods, and one of those local methods has no section on the page. The entry labelled with a command-line tool links to a heading that is not present.

That is the widest part of the project and the least coherent. Five deployment shapes means five places where a variable name, a start command or a working directory can drift, and the sample configuration has already drifted from the compose file.

What holds it together is the single start script every method ultimately invokes, which is the right way round: the divergence is confined to how you get there rather than to what happens once running.

Some of this is inherent. A userbot is an awkward deployment target because it wants a long-lived process, a session that survives restarts, and outbound-only connectivity with no inbound port. Five manifests is a reasonable answer to that, and the compose file's lack of ports is evidence the author understood the shape.

The plugin directory, the assistant directory and the strings directory are where the actual surface lives, and none of them appears in the navigation.

Three releases, two on one evening, none in four years

The release history has three entries. Two were published on the same evening at the end of 2021, a few hours apart, and the lower-numbered of the two carries a title saying it was a late release. The third, and newest, is from August 2022.

The last push to the main branch is from July 2026, so roughly four years of commits sit past the newest tag.

That gap is the first thing to establish before evaluating anything else in this project. If you are deciding whether to run it, you are choosing between a four-year-old tagged release and an untagged branch that has moved considerably since, and the documentation will not tell you which of the two you have.

It also sits oddly against the first line of the page, which describes the project as stable. Nothing on the page dates that claim, and the version numbers anyone can see have been frozen at 0.7 while the branch moved on.

One more thing to know before you go looking for this project, because it wastes time otherwise. The name is shared with a medical treatment for a specific condition and with a fictional character from a superhero franchise. Most searches for the name will not reach this repository, and the questions people actually ask about it tend to be about one of the other three things it is called.

Editorial conclusion

Judge this on two questions before anything else. Does the account you would log in with matter more than the features, because a userbot acts as you rather than as a bot, and a session token does not expire the way a password does. And are you willing to have your install pull mutable third-party code, because that decision is made in the requirements file rather than by you. If both answers are comfortable and you generate the session locally yourself, the project is a capable pluggable base with a wide plugin surface. If either is not, the feature list is not the reason to proceed. And pin a commit rather than a tag, since the newest tag is four years old and will not tell you what you are running.

Frequently asked questions

What is Ultroid?

A pluggable Telegram userbot plus a voice and video call music bot, built on the Telethon library and licensed under the AGPL v3 or later. It acts as a user account rather than a bot account, and it is deployed either to a hosting platform or locally with a start script.

Is Ultroid safe to run with your Telegram account?

Assess two things first. It runs as a user account, not a bot, so its actions are attributed to you. And its only mandatory variable is an authenticated session token rather than a password, which does not expire the way a password does. Its requirements file also installs an unpinned fork of its core library from another person's branch.

Is Ultroid still maintained?

The newest release tag is v0.7, published 2022-08-31, while the last push to the main branch was 2026-07-23. There are three releases in total and two of them were published on the same evening in December 2021, one of them titled as a late release.

How do I install Ultroid on a local machine?

The traditional method is a clone, a virtual environment, two requirements installs, a generated session string, and then a start script. An easier one-line method downloads and runs a Python installer from a shortened URL, which means you cannot inspect the script before executing it.

What licence is Ultroid released under?

The GNU Affero General Public License v3 or later, with a LICENSE file at the repository root, and the Dockerfile carries a matching licence header crediting the team.

Official sources

  1. License: AGPL-3.0
  2. Project website
  3. README
  4. Releases
  5. TeamUltroid/Ultroid on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/teamultroid-ultroid.svg)](https://hysenlabs.com/projects/teamultroid-ultroid)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/teamultroid-ultroid.svg)](https://hysenlabs.com/projects/teamultroid-ultroid)

Was this useful?