---
title: Telegram Stremio
emoji: π¬
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 8000
pinned: false
---
A powerful, self-hosted Telegram Stremio Media Server built with FastAPI, MongoDB, and PyroFork β seamlessly integrated with Stremio for automated media streaming and discovery.
---
## π§ Quick Navigation
* [π Introduction](#-introduction)
* [β¨ Key Features](#-key-features)
* [π³ Subscription Management](#-subscription-management)
* [π Subscription Plans](#-subscription-plans)
* [π€ Bot Payment Flow](#-bot-payment-flow)
* [ποΈ Access Management](#οΈ-access-management)
* [π¬ Stremio Addon Integration](#-stremio-addon-integration)
* [βοΈ How It Works](#οΈ-how-it-works)
* [π Overview](#overview)
* [π€ Upload Guidelines](#upload-guidelines)
* [π Quality Replacement Logic](#-quality-replacement-logic)
* [π₯ Updating CAMRip or Low-Quality Files](#-updating-camrip-or-low-quality-files)
* [βοΈ Behind the Scenes](#behind-the-scenes)
* [π€ Bot Commands](#-bot-commands)
* [π Command List](#command-list)
* [βοΈ /set Command Usage](#set-command-usage)
* [π§ Configuration Guide](#-configuration-guide)
* [πͺ Step 1: Create Your config.env File](#-step-1-create-your-configenv-file)
* [π Step 2: How to Get Each Value](#-step-2-how-to-get-each-value)
* [π± Step 3: Generate Your Telegram Session String](#-step-3-generate-your-telegram-session-string)
* [𧩠Step 4: Configure Everything Else (Web Settings Page)](#-step-4-configure-everything-else-web-settings-page)
* [π Deployment Guide](#-deployment-guide)
* [β
Recommended Prerequisites](#-recommended-prerequisites)
* [π Heroku Guide](#-heroku-guide)
* [π³ VPS Guide (Recommended)](#-vps-guide-recommended)
* [π€ Hugging Face Guide](#-hugging-face-guide)
* [πΊ Setting Up Your App (Nuvio Recommended)](#-setting-up-your-app-nuvio-recommended)
* [π₯ Install Nuvio](#-step-1-install-nuvio)
* [π Add the Addon](#-step-2-add-the-addon)
* [π
Contributors](#-contributors)
# π Introduction
This project is a **next-generation Telegram Stremio Media Server** that allows you to **stream your Telegram files directly through Stremio**, without any third-party dependencies or file expiration issues. Itβs designed for **speed, scalability, and reliability**, making it ideal for both personal and community-based media hosting.
## β¨ Key Features
- βοΈ **Multiple MongoDB Database Support**
- π‘ **Multiple Telegram Channel Support**
- β‘ **Ultra-Fast Streaming Experience**
- π **Multi-Token Load Balancer**
- π¬ **IMDb & TMDb Metadata Integration**
- 𧩠**Seamless Split File Streaming Support**
- ποΈ **Play Multi-Part Videos as a Single Stream**
- βΎοΈ **Permanent Streaming Links (No Expiration)**
- π§ **Powerful Admin Dashboard**
- π³ **Subscription & Premium Management**
- π **Advanced Access Control System**
- π **Custom & Automatic Catalog Generation**
- π₯οΈ **Web-Based Configuration Panel**
- π **Built-in Addon Proxy Support**
- π **Global Search Across Selected Channels**
## βοΈ How It Works
This project acts as a **bridge between Telegram storage and Stremio streaming**, connecting **Telegram**, **FastAPI**, and **Stremio** to enable seamless movie and TV show streaming directly from Telegram files.
### Overview
When you **forward Telegram files** (movies or TV episodes) to your **AUTH CHANNEL**, the bot automatically:
1. ποΈ **Stores** the `message_id` and `chat_id` in the database.
2. π§ **Processes** file captions to extract key metadata (title, year, quality, etc.).
3. π **Generates a streaming URL** through the **PyroFork** module β routed by **FastAPI**.
4. ποΈ **Provides Stremio Addon APIs**:
- `/catalog` β Lists available media
- `/meta` β Shows detailed information for each item
- `/stream` β Streams the file directly via Telegram
### Upload Guidelines
To ensure proper metadata extraction and seamless integration with **Stremio**, all uploaded Telegram media files **must include specific details** in their captions.
#### π₯ For Movies
**Example Caption:**
```
Ghosted 2023 720p 10bit WEBRip [Org APTV Hindi AAC 2.0CH + English 6CH] x265 HEVC Msub ~ PSA.mkv
```
**Required Fields:**
- ποΈ **Name** β Movie title (e.g., _Ghosted_)
- π
**Year** β Release year (e.g., _2023_)
- πΊ **Quality** β Resolution or quality (e.g., _720p_, _1080p_, _2160p_)
β
**Optional:** Include codec, audio format, or source (e.g., `WEBRip`, `x265`, `Dual Audio`).
#### πΊ For TV Shows
**Example Caption:**
```
Harikatha.Sambhavami.Yuge.Yuge.S01E04.Dark.Hours.1080p.WEB-DL.DUAL.DDP5.1.Atmos.H.264-Spidey.mkv
````
**Required Fields:**
- ποΈ **Name** β TV show title (e.g., _Harikatha Sambhavami Yuge Yuge_)
- π **Season Number** β Use `S` followed by two digits (e.g., `S01`)
- π¬ **Episode Number** β Use `E` followed by two digits (e.g., `E04`)
- πΊ **Quality** β Resolution or quality (e.g., _1080p_, _720p_)
β
**Optional:** Include episode title, codec, or audio details (e.g., `WEB-DL`, `DDP5.1`, `Dual Audio`).
### π Quality Replacement Logic
> Works only when **Replace Mode** is enabled.
If a newly uploaded file has the same quality label (`720p`, `1080p`, `4K`, etc.) as an existing file, the bot automatically replaces the older entry with the new one.
**Example:** Uploading a new `Ghosted (2023) 720p` file will replace the existing `720p` version in the catalog.
This prevents duplicate quality entries and ensures only the latest version is available for streaming.
---
### π Updating CAMRip or Low-Quality Files
> Works only when **Replace Mode** is enabled.
If you initially uploaded a **CAMRip or low-quality version**, you can easily replace it with a better one:
1. Forward the **new, higher-quality file** (e.g., `1080p`, `WEB-DL`) to your **AUTH CHANNEL**.
2. The bot will **automatically detect and replace** the old CAMRip file in the database.
3. The Stremio addon will then **update automatically**, showing the new stream source.
β
No manual deletion or command is needed β forwarding the updated file is enough!
---
### π·οΈ Fixing Incorrect Metadata (Manual Override)
If the addon identifies a movie or TV show incorrectly, or if metadata is missing altogether, you can easily correct it using one of the following methods:
#### Method 1: IMDb / TMDb URL Override
1. Copy the correct **IMDb** or **TMDb** URL for the movie or TV show.
2. Edit the message caption in your Telegram **AUTH CHANNEL** and paste the URL anywhere in the caption.
3. The bot will automatically:
* Remove the existing metadata entry associated with that file.
* Re-scan the provided URL.
* Fetch and save the correct metadata.
#### Method 2: Scan Metadata from the Web Panel
1. Open the media entry from the Movies or TV Shows section.
2. Click **Edit**.
3. Select **Scan Metadata**.
4. Search for the correct title and choose the matching result.
5. Apply the changes.
β
The addon will update the metadata instantly and refresh the catalog entry.
---
### Behind The Scenes
Here's how each component interacts:
| Component | Role |
| :--- | :--- |
| **Telegram Bot** | Handles uploads, forwards, and file tracking. |
| **MongoDB** | Stores message IDs, chat IDs, and metadata. |
| **PyroFork** | Generates Telegram-based streaming URLs. |
| **FastAPI** | Hosts REST endpoints for streaming, catalog, and metadata. |
| **Stremio Addon** | Consumes FastAPI endpoints for catalog display and playback. |
π¦ **Flow Summary:**
```
Telegram β MongoDB β FastAPI β Stremio β User Stream
```
# π€ Bot Commands
Below is the list of available bot commands and their usage within the Telegram bot.
### Command List
| Command | Description |
| :--- | :--- |
| **`/start`** | Returns your **Addon URL** for direct installation in **Stremio**. |
| **`/log`** | Sends the latest **log file** for debugging or monitoring. |
| **`/set`** | Used for **manual uploads** by linking IMDB URLs. |
| **`/restart`** | Restarts the bot and pulls any **latest updates** from the upstream repository. |
### `/set` Command Usage
The `/set` command is used to manually upload a specific Movie or TV show to your channel, linking it to its IMDB metadata.
**Command:**
```
/set
```
**Example:**
```
/set https://www.imdb.com/title/tt0468569/
```
**Steps:**
1. Send the `/set` command followed by the **IMDB URL** of the movie or show you want to upload.
2. **Forward the related movie or TV show files** to your channel.
3. Once all files are uploaded, **clear the default IMDB link** by simply sending the `/set` command without any URL.
π‘ **Tip:** Use `/log` if you encounter any upload or parsing issues.
# π§ Configuration Guide
> π **Donβt worry β setup is easier than it looks.**
> You only fill in **6 values once** inside a single file called `config.env`. Everything else (TMDB key, channels, admin login, subscriptions, proxyβ¦) is configured later from a friendly **Web Settings page** β no code, no restarts.
Think of configuration as **two simple layers**:
| Layer | Where | When you set it | What goes here |
| :--- | :--- | :--- | :--- |
| 𧱠**Startup** | `config.env` file | Once, before first launch | The core credentials needed to boot |
| ποΈ **Runtime** | **Web Settings page** | Anytime, after launch | Everything else β saved to the database, applied live |
---
## πͺ Step 1: Create Your config.env File
After cloning the project, copy the sample file and open it for editing:
```bash
cp sample_config.env config.env
nano config.env
```
Fill in these values:
| Variable | Required | What it is |
| :--- | :---: | :--- |
| `API_ID` | β
| Telegram API ID (from my.telegram.org) |
| `API_HASH` | β
| Telegram API Hash (from my.telegram.org) |
| `BOT_TOKEN` | β
| Your bot token (from @BotFather) |
| `OWNER_ID` | β
| Your numeric Telegram user ID |
| `DATABASE` | β
| **Two** MongoDB URIs, separated by a comma |
| `PORT` | β
| Web server port (keep `8000` unless itβs busy) |
| `USER_SESSION_STRING` | β¬ | Optional β only needed for **Global Search** |
A completed file looks like this (these are just example values):
```env
API_ID="1234567"
API_HASH="abc123def456ghi789jkl012mno345pq"
BOT_TOKEN="1234567890:AAEabcdEFGhijkLMnOPqrsTUVwxyz12345"
USER_SESSION_STRING=""
OWNER_ID="987654321"
DATABASE="mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/tracking,mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/storage1"
PORT="8000"
```
> πΎ To save in nano: press `Ctrl + O`, then `Enter`, then `Ctrl + X`.
---
## π Step 2: How to Get Each Value
Take it one line at a time β each value comes from a quick, free step.
### π API_ID & API_HASH
1. Go to **https://my.telegram.org** and log in with your phone number.
2. Open **API development tools**.
3. Create an app (any title works, e.g. `stremio`).
4. Copy **App api_id** β `API_ID` and **App api_hash** β `API_HASH`.
### π€ BOT_TOKEN
1. Open **@BotFather** in Telegram.
2. Send `/newbot` and follow the prompts (choose a name and a username).
3. Copy the token it gives you β `BOT_TOKEN`.
4. β Add this bot as an **admin** in every channel youβll use for media.
### π€ OWNER_ID
1. Open **@userinfobot** in Telegram (or send `/id` to **@MissRose_bot**).
2. It replies with your numeric ID β `OWNER_ID`.
### ποΈ DATABASE (two MongoDB URIs)
You need **two** free MongoDB databases β the first stores tracking/metadata, the second stores your media references.
1. Create a free account at **https://www.mongodb.com/atlas** (the forever-free **M0** tier is enough to start).
2. Create a cluster β in **Database Access**, add a database user and password.
3. In **Network Access**, add `0.0.0.0/0` (allow access from anywhere).
4. Click **Connect β Drivers** and copy the connection string, e.g.
`mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/`
5. Add a database name at the end of each (e.g. `/tracking` and `/storage1`).
6. Put **both** strings on one line, separated by a comma:
```
DATABASE="mongodb+srv://.../tracking,mongodb+srv://.../storage1"
```
> π‘ You can use the **same cluster** for both β just give them two different database names. Need more space later? Add extra storage databases from the Web Settings page (no restart required).
### π’ PORT
Leave it as `8000` unless that port is already in use. Your reverse proxy / domain will point here.
### π± USER_SESSION_STRING (optional)
Only needed if you want **Global Search**. Itβs safe and quick to generate β see **Step 3** below. If you donβt need Global Search, leave it empty.
---
## π± Step 3: Generate Your Telegram Session String
> π **No app installation required β and itβs safe.**
> A session string is simply a βstay logged inβ token for **your own** Telegram account, exactly like signing into Telegram Web. The bot never sees your password, and you can revoke access anytime from **Telegram β Settings β Devices**.
> βοΈ **Skip this step** entirely if you donβt plan to use Global Search.
### π Easiest Method: Google Colab (works right in your phoneβs browser)
1οΈβ£ Open **https://colab.new** in your browser.
2οΈβ£ Sign in with your Google account.
3οΈβ£ Tap **β+ Codeβ** to add a new code cell.
4οΈβ£ Paste the code below and press βΆ **Run**:
```python
!pip install pyrogram tgcrypto
import asyncio
from pyrogram import Client
api_id = int(input("API ID: "))
api_hash = input("API HASH: ")
async def main():
async with Client("temp_session", api_id, api_hash) as app:
print("\nYour USER_SESSION_STRING is:\n")
print(await app.export_session_string())
await main()
```
5οΈβ£ Enter your **API ID** and **API HASH** when prompted.
6οΈβ£ Enter the **login code** Telegram sends you (and your 2-step password, if you have one).
7οΈβ£ Your **USER_SESSION_STRING** is printed on screen β copy the whole string into `config.env`.
> π **Keep it private.** Anyone who has this string can access your account, so never share it or commit it to a public repository. To invalidate it instantly, just remove the session from Telegramβs **Devices** list.
---
## 𧩠Step 4: Configure Everything Else (Web Settings Page)
Once the server is running, open it in your browser:
| Setup | Open this URL |
| :--- | :--- |
| **VPS with a domain** | `https://your-domain.com` |
| **Local / direct IP** | `http://:8000` |
Youβll land on the **login page** (`/login`). Sign in with the default credentials:
```
Username: admin
Password: admin
```
Then go to **Settings** (`/admin/settings`).
> π¨ **Do this first:** change the admin password in the **Admin Authentication** card, then click **Save Settings**.
Everything below is stored in the database and applied **instantly β no restart needed** (the only exception is `USER_SESSION_STRING`, which lives in `config.env`).
### βοΈ General
| Option | What it does |
| :--- | :--- |
| **Replace Mode** | When a new file has the same quality (`720p`, `1080p`β¦) as an existing one, it replaces the old entry. Recommended **ON**. |
| **Hide Catalog** | Hides the public Stremio catalog (direct streams still work). |
### π‘οΈ Admin Authentication
| Field | What to enter |
| :--- | :--- |
| **Admin Username / Password** | Your Web Panel login. Leave the password blank to keep the current one. **Change the defaults right away.** |
| **AUTH_CHANNELS** | The channel(s) the bot indexes and streams from. Add each one by `@username` or `-100β¦` ID. Make sure your bot is an **admin** in each channel. |
### π¬ Media & Content
| Field | What to enter |
| :--- | :--- |
| **TMDB API Key** | A free TMDB **v3** key from themoviedb.org β Settings β API. Powers automatic metadata matching. |
| **Base URL** | Your public address, e.g. `https://your-domain.com`. **Important:** Stremio uses this to reach your streams. |
| **Upstream Repo / Branch** | Optional β used by `/restart` to auto-update (e.g. repo `weebzone/Telegram-Stremio`, branch `master`). |
### π³ Subscription (optional)
Turn this on to monetise access. Set the **Subscription Group ID**, **Payment Instructions** (your UPI / bank / PayPal text), an optional **Payment QR image URL**, and the **Approver IDs** (who can approve requests). Renewal and "join the channel" prompts shown in Stremio point users back to **your bot automatically** β no separate URL to configure. The full flow is described in [Subscription Management](#-subscription-management).
### π Global Search (optional)
Requires `USER_SESSION_STRING` in `config.env` plus one app restart to unlock. Then enable the toggle and add the **channel IDs** to search. Results that arenβt in your local catalog are tagged **π GLOBAL** in Stremio.
### π Proxy (optional)
Set an **HTTP Proxy URL** for outbound metadata/API requests, and optionally **show both** proxied and direct stream links.
### ποΈ Extra Storage Databases
Your first two databases (from `config.env`) are **locked** as *Tracking* and *Storage 1*. Add more MongoDB URIs here to expand storage capacity β π’ means connected. Remove entries only from the **end** of the list, since existing media reference databases by position.
### π¨ Multi-Token Clients
Add extra **bot tokens** for faster parallel streaming under heavy load. Create more bots with @BotFather, add them as **admins** in all your AUTH channels, then paste their tokens here. Changes apply immediately.
> β
Click **Save Settings** when youβre done. Thatβs it β youβre live!
---
# π³ Subscription Management
The Subscription Management system allows you to **monetise access** to your Telegram Stremio server. When enabled, users must have an active subscription to stream content.
## π Subscription Plans
Admins can create and manage subscription plans from the **Admin Panel β Subscription Management** page.
Each plan has:
- **Name** (e.g. `Monthly`, `Quarterly`)
- **Duration** in days
- **Price** (for display)
- **Description**
Plans are stored in MongoDB and can be added, edited, or deleted at any time without restarting.
---
## π€ Bot Payment Flow
Users interact with the bot to subscribe:
```
User β /start β selects plan β sends payment screenshot
β Approver gets notification β Approve / Reject
β On Approve:
β
Subscription saved to DB
π Stremio addon token auto-generated
π¨ User receives Stremio install link + group invite
```
**Approver actions** (available to `APPROVER_IDS`):
| Button | Action |
| :--- | :--- |
| β
Approve | Activates subscription, generates addon token, invites user to group |
| β Reject | Notifies user with rejection message |
---
## ποΈ Access Management
The **Admin Panel β Access Management** page gives admins full control over all users and their addon tokens.
### Columns Shown
| Column | Description |
| :--- | :--- |
| Status | π’ Active / π΄ Expired |
| User | Display name or `User {id}` |
| Addon Link | Stremio install URL + copy button |
| Created | Token creation date |
| Expires | Subscription expiry date |
| Actions | Buttons for managing the user |
### Action Buttons
| Button | Description |
| :--- | :--- |
| π
**Assign** | Assign or extend a subscription plan (adds days) |
| β **Extend** | Add extra days to an active subscription |
| β **Reduce** | Subtract days from an active subscription |
| π« **Revoke** | Wipe subscription entirely (marks expired) |
| ποΈ **Del Token** | Delete the addon token only (user still subscribed) |
| π **Link User ID** | Link an old/orphan token to a Telegram user ID to enable management |
> π‘ Manually created (old) tokens that have no linked user ID show a **π Link User ID** button. Once linked, all action buttons become available.
### Search & Filtering
- π Search by user name or ID
- Filter by status: All / Active / Expired
- Pagination with configurable page size
---
## π¬ Stremio Addon Integration
### Per-User Addon Token
Each user gets a **unique addon token** automatically generated on payment approval. Their Stremio addon URL is:
```
https://your-domain.com/stremio/{token}/manifest.json
```
### Dynamic Manifest
The addon manifest updates dynamically per user:
| Scenario | Addon Name | Description |
| :--- | :--- | :--- |
| Active, has expiry | `Telegram β Expires 28 Mar 2026` | π
Subscription active until 28 Mar 2026 |
| Active, no expiry | `Telegram β Active` | β
Subscription active |
| Default (no subscription mode) | `Telegram` | Standard description |
The manifest `version` encodes the expiry date β when an admin extends or revokes a subscription, the version changes and Stremio detects an update.
### Subscription Stream Gating
When the subscription feature is enabled, the addon checks every stream request and shows a single actionable entry instead of the streams when the user isn't eligible. In both cases the stream link opens **your bot** (derived automatically from the bot's username β there is no URL to configure).
**Plan expired** β the user's subscription has lapsed:
```json
{
"name": "π« Plan Expired",
"title": "Your plan is expired.\nRenew it from the bot to continue watching.",
"url": "https://t.me/your_bot"
}
```
**Not joined** β the user is active but has left / never joined the subscription channel (the `Subscription Group ID`):
```json
{
"name": "π’ Join Required",
"title": "First join the channel to stream it.\nTap here to open the bot and join.",
"url": "https://t.me/your_bot"
}
```
Clicking the stream name opens the bot directly so the user can renew or rejoin. The membership check fails open β if Telegram is briefly unreachable or the bot can't read the group, legitimate users are never blocked.
### Configure & Reinstall Page
Every addon has a **Configure page** at:
```
https://your-domain.com/stremio/{token}/configure
```
This page shows:
- User name, subscription status, expiry date
- **β‘ Install / Update in Stremio** button (Stremio Web install flow)
- Manual install steps + **π Copy URL** button
The βοΈ gear icon in Stremio opens this page so users can reinstall after an admin updates their subscription.
---
# π Deployment Guide
This guide will help you deploy your **Telegram Stremio Media Server** using either Heroku or a VPS with Docker.
## β
Recommended Prerequisites
**Supported Servers:**
- π£ **Heroku**
- π’ **VPS**
Before you begin, ensure you have:
1. β
A **VPS** with a public IP (e.g., Ubuntu on DigitalOcean, AWS, Vultr, etc.)
2. β
A **Domain name**
## π Heroku Guide
Follow the instructions provided in the Google Colab Tool to deploy on Heroku.
[](https://colab.research.google.com/github/weebzone/Colab-Tools/blob/main/telegram%20stremio.ipynb)
## π³ VPS Guide
This section explains how to deploy your **Telegram Stremio Media Server** on a VPS using **Docker Compose (recommended)** or **Docker**.
### 1οΈβ£ Step 1: Clone & Configure the Project
```bash
git clone https://github.com/weebzone/Telegram-Stremio
cd Telegram-Stremio
mv sample_config.env config.env
nano config.env
```
* Fill in all required variables in `config.env`.
* Press `Ctrl + O`, then `Enter`, then `Ctrl + X` to save and exit.
## βοΈ Step 2: Choose Your Deployment Method
You can deploy the server using either **Docker Compose (recommended)** or **plain Docker**.
### π’ **Option 1: Deploy with Docker Compose (Recommended)**
Docker Compose provides an easier and more maintainable setup, environment mounting, and restart policies.
#### π Start the Container
```bash
docker compose up -d
```
Your server will now be running at:
β‘οΈ `http://:8000`
---
#### π οΈ Update `config.env` While Running
If you need to modify environment values (like `BASE_URL`, `AUTH_CHANNEL`, etc.):
1. **Edit the file:**
```bash
nano config.env
```
2. **Save your changes:** (`Ctrl + O`, `Enter`, `Ctrl + X`)
3. **Restart the container to apply updates:**
```bash
docker compose restart
```
β‘ Since the config file is mounted, you **donβt need to rebuild** the image β changes apply automatically on restart.
### π΅ **Option 2: Deploy with Docker (Manual Method)**
If you prefer not to use Docker Compose, you can manually build and run the container.
#### 𧩠Build the Image
```bash
docker build -t telegram-stremio .
```
#### π Run the Container
```bash
docker run -d -p 8000:8000 telegram-stremio
```
Your server should now be running at:
β‘οΈ `http://:8000`
### π Step 3: Add Domain (Required)
#### π
°οΈ Set Up DNS Records
Go to your domain registrar and add an **A record** pointing to your VPS IP:
| Type | Name | Value |
| ---- | ---- | ----------------- |
| A | @ | `195.xxx.xxx.xxx` |
#### 𧱠Install Caddy (for HTTPS + Reverse Proxy)
```bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
```
#### βοΈ Configure Caddy
1. **Edit the Caddyfile:**
```bash
sudo nano /etc/caddy/Caddyfile
```
2. **Replace contents with:**
```caddy
your-domain.com {
reverse_proxy localhost:8000
}
```
* Replace `your-domain.com` with your actual domain name.
* Adjust the port if you changed it in `config.env`.
3. **Save and reload Caddy:**
```bash
sudo systemctl reload caddy
```
β
Your API will now be available securely at:
β‘οΈ `https://your-domain.com`
## π€ Hugging Face Guide
Deploy a **free, always-online** instance β no VPS, no domain, and no Docker knowledge required. Hugging Face builds the Docker image **on its own servers**; you only tap a few buttons.
> π‘ **How it works:** this repo ships a GitHub Action that automatically pushes your code to your Hugging Face Space on every change. The Space then builds the included `Dockerfile` and runs your server.
### β Step 1: Star this Repository
Open the repo and tap **β Star** at the top right. It helps the project and keeps it on your radar.
β‘οΈ [github.com/weebzone/Telegram-Stremio](https://github.com/weebzone/Telegram-Stremio)
### π΄ Step 2: Fork the Repository
Tap **Fork** (top right) β **Create fork**. This gives you your **own copy** so you can add private secrets and run the deploy workflow.
### π Step 3: Create a Hugging Face Write Token
1. Sign in (or sign up) at [huggingface.co](https://huggingface.co).
2. Go to **Profile β Settings β Access Tokens**.
3. Tap **Create new token**, choose the **Write** role, and copy the token.
### π Step 4: Create a Docker Space
1. Go to [huggingface.co/new-space](https://huggingface.co/new-space).
2. Give it a name, select **Docker** as the SDK (pick the **Blank** template).
3. Set visibility to **Public** (required so Stremio/Nuvio can reach your addon).
4. Tap **Create Space**.
Your Space ID is `/` β note it down.
### π Step 5: Add Deploy Credentials to Your GitHub Fork
In **your forked repo** β **Settings β Secrets and variables β Actions**:
| Type | Name | Value |
| ------------ | ------------- | -------------------------------------- |
| **Secret** | `HF_TOKEN` | the Write token from Step 3 |
| **Variable** | `HF_SPACE_ID` | `/` |
> Add the secret under the **Secrets** tab and the variable under the **Variables** tab.
### π€ Step 6: Add Your Bot Secrets to the Space
On your **Hugging Face Space β Settings β Variables and secrets**, add the same values you'd normally put in `config.env`:
| Secret | Required | Where to get it |
| --------------------- | -------- | -------------------------------------- |
| `API_ID` | β
| [my.telegram.org](https://my.telegram.org) |
| `API_HASH` | β
| [my.telegram.org](https://my.telegram.org) |
| `BOT_TOKEN` | β
| [@BotFather](https://t.me/BotFather) |
| `OWNER_ID` | β
| your numeric Telegram ID |
| `DATABASE` | β
| two comma-separated MongoDB URIs |
| `USER_SESSION_STRING` | β¬ | optional (Global Search) |
> βΉοΈ You don't need a `config.env` file on Hugging Face β these secrets are read directly as environment variables. The included `Dockerfile` already listens on the right port (`app_port: 8000` is preset in this README).
### βΆοΈ Step 7: Deploy
In **your forked repo** β **Actions** tab β select **Deploy to Hugging Face Space** β **Run workflow**.
After this first run, **every push to your fork auto-deploys**. Watch the build progress on your Hugging Face Space page β once it shows **Running**, you're live.
### π¬ Step 8: Use Your Addon
1. Open `https://-.hf.space/login`
2. Log in (default `admin` / `admin`) and **immediately change the password**.
3. Set your **Base URL** in the web Settings page to `https://-.hf.space`.
4. Now open bot and send /start command it give you the manifest url
5. Add the manifest URL to Stremio/Nuvio and enjoy. π
### π¬ Step 9: Setup the Additional value
1. Go to Web settings page `https://-.hf.space/admin/settings`.
2. Fill up the TMDB API, AUTH CHANNEL.
3. If you need to fill up other things check [Web Settings](#-step-4-configure-everything-else-web-settings-page)
4. Save the settings and enjoy.
# πΊ Setting Up Your App (Nuvio Recommended)
Your media server works as a standard **Stremio-style addon**, so it plays in any compatible client. For the **best compatibility and smoothest experience across devices, we recommend the [Nuvio](https://play.google.com/store/apps/details?id=com.nuvio.app) app** β a free, open-source media hub for **Android, Android TV, Fire TV, iOS, Windows, and TV** that supports Stremio addon manifest URLs natively. *(Content was rephrased for compliance with licensing restrictions.)*
> π‘ Already using **Stremio**? It works too β just install the same addon URL below. Nuvio simply tends to handle these Telegram streams more reliably across more devices.
## π₯ Step 1: Install Nuvio
Download Nuvio from an official source:
| Platform | Source |
| :--- | :--- |
| **Android / Android TV / Fire TV** | [Google Play](https://play.google.com/store/apps/details?id=com.nuvio.app) |
| **All platforms / latest builds** | [GitHub β tapframe/NuvioStreaming](https://github.com/tapframe/NuvioStreaming) |
> π *(Optional)* Connect **Trakt** in the app to sync your watch history and progress across devices.
## π Step 2: Add the Addon
1. Open **Nuvio** and go to the **Addons** section.
2. Paste your addon **manifest URL** and install it:
3. Done! π Your Telegram library now appears in the catalog and streams directly.
## π
Contributors
|
|
|
|
|
|:---:|:---:|:---:|:---:|
|[`Karan`](https://github.com/Weebzone)|[`Stremio`](https://github.com/Stremio)|[`ChatGPT`](https://github.com/OPENAI)|[`VFlix Prime`](https://t.me/vflixprime2)|
|Author|Stremio SDK|Refactor|Community Support