Documentation menu

Getting started

New in v2.0

Feature deep dives

System atlas

Reference

Learn

Installation

Install a Self-Hosted Telegram Forwarder

Install AutoTelegramForward v2.2.4: pick a deployment path, run the guided setup, then prove all four services are serving before you trust it.

Verified against the checkout built for v2.2.4 · updated 20 Oct 2026

On this page

What you need
Deployment paths
Guided install
After install

One decision first: how do you want to run it? Everything after that is the same — the wizard, the CLI, the bot and the dashboard are identical on every path, so you are not locked in by an install choice.

What you need

v2.2.4 — runtime requirements
Requirement	Details
Hardware	1 vCPU, 512 MB RAM (1 GB for heavy media), ~2 GB disk plus media staging headroom.
Software	Docker Engine 24+ with Compose v2, or Python 3.10+ for a native install.
Telegram	An account with `api_id` / `api_hash` from my.telegram.org, and a bot token from @BotFather.
Network	Outbound access to Telegram. Inbound only if you publish the dashboard.
Secrets	A bot token, your numeric admin user id, and a database URL if you are not using SQLite.

Hardware
Details
1 vCPU, 512 MB RAM (1 GB for heavy media), ~2 GB disk plus media staging headroom.
Software
Details
Docker Engine 24+ with Compose v2, or Python 3.10+ for a native install.
Telegram
Details
An account with api_id / api_hash from my.telegram.org, and a bot token from @BotFather.
Network
Details
Outbound access to Telegram. Inbound only if you publish the dashboard.
Secrets
Details
A bot token, your numeric admin user id, and a database URL if you are not using SQLite.

Deployment paths

Docker ComposeRecommended

Four containers, one compose file, one command. The path most operators should take.

Best when: A host you control, with Docker installed.

Linux installer / wizardBare metal

Installer script or interactive wizard, then a systemd unit that survives reboots.

Best when: A VPS or home server where you want native services.

WindowsDesktop / server

PowerShell bootstrap of a checkout, same wizard, same CLI afterwards.

Best when: Windows 10/11 or Windows Server.

From sourceDevelopment

Virtualenv, requirements, run the services yourself with hot reload.

Best when: You are changing the code.

Guided install

The wizard detects your platform, validates every answer as you type it, builds the stack, and finishes by probing each service. It does not say "done" unless it can prove it.

1
Fetch the source
```
git clone https://github.com/Opselon/AutoTelegramForward.git
cd AutoTelegramForward
```
Every install path starts from the same checkout, so the CLI and the bot are identical afterwards.

Run the wizard

# Linux / macOS
./scripts/setup.sh

# re-run or automate a known-good config
./scripts/setup.sh --yes
./scripts/setup.sh --answers answers.json

# Windows
python scripts\bootstrap.py

The wizard detects the platform, validates each answer as you give it, and refuses to continue on a malformed value.

Prove it is serving

atf status             # ports, reachability, task counts
atf validate --strict  # config, compose, catalog parity, secrets
atf doctor             # deeper checks; --fix repairs what it can

The install is only finished when these three are clean. "Running" and "serving" are different claims.

Open the interfaces
Dashboard on :8088, REST API on :8080, core gRPC on :50051.
Message the bot with /settings to create your first task, or use atf rules create.

After install

Telegram credentials — Bot token, api_id/api_hash and the first admin login.
Configuration reference — Every environment key, whether it is secret and what it changes.
Verification checklist — Prove each service is serving, not merely running.
Your first task — Recipes with real commands, in increasing difficulty.
Operations runbook — What to do when something is red.