Reddit's top posts, delivered to Telegram

Install · Commands · Configuration · Deployment

A self-hosted Telegram bot that monitors your favorite subreddits and sends you the top posts. All media is embedded directly in Telegram thanks to yt-dlp — no need to open Reddit.

Requires yt-dlp and ffmpeg at runtime for media downloads.

curl -fsSL https://raw.githubusercontent.com/raine/tgreddit/master/scripts/install.sh | bash

Download from GitHub releases:

cargo install tgreddit

Pre-built image with all dependencies included:

docker pull rainevi/tgreddit

See Docker deployment below.

Subscribe to a subreddit's top posts. The bot periodically checks the subreddit's top posts and sends you any new ones that appear. Subscriptions are per-conversation — add them in channels or private chats.

• time — the time window to watch: hour, day, week, month, year, all. Think of it as "top posts of the ___". Default: day.
• limit — how many top posts to watch. With limit=3, you'll see posts as they enter the top 3. Higher means more posts. Default: 1.
• filter — only send certain post types: image, video, link, self_text, gallery.

When called with just a subreddit name, the bot replies with an inline keyboard to configure settings interactively. If you already know the parameters you want, pass them directly:

/sub AnimalsBeingJerks /sub AnimalsBeingJerks time=week limit=5 /sub AnimalsBeingJerks time=week filter=video 

Remove a subscription from the current conversation.

List all subscriptions for the current conversation as an interactive inline keyboard. Tapping a subscription opens an edit menu where you can:

• Cycle limit — tap to cycle through 1, 3, 5, 10, 25
• Cycle time period — tap to cycle through hour, day, week, month, year, all
• Cycle filter — tap to cycle through all, image, video, link, self_text, gallery
• Pause / Resume — pause a subscription so it stops checking for new posts without losing its settings
• Unsubscribe — remove the subscription

One-shot fetch of current top posts without subscribing. Accepts the same time, limit, and filter options as /sub.

Full example: config.example.toml

# Path to SQLite database for tracking seen posts. # Optional. Defaults to $HOME/.local/state/tgreddit/data.db3. db_path = "/path/to/data.db3" # Telegram user IDs allowed to use bot commands. authorized_user_ids = [123123123] # Bot token from @BotFather. telegram_bot_token = "..." # How often to check for new posts (seconds). check_interval_secs = 600 # Skip sending posts found on first check of a new subreddit. # Prevents a flood of messages when adding a subscription. # Optional. Default: true. skip_initial_send = true # Use an alternative Reddit frontend for comment links. # Optional. Default: official Reddit. links_base_url = "https://teddit.net" # Default time window for top posts: hour, day, week, month, year, all. # Think of it as "top posts of the ___". # Optional. Default: day. default_time = "day" # Default number of top posts to watch per subreddit. # With limit=3, you'll see posts as they enter the top 3. # Optional. Default: 1. default_limit = 1 # Default post type filter: image, video, link, self_text, gallery. # Optional. Default: unset (all types). default_filter = "video"

Tip: The easiest way to find a Telegram channel's ID is to open it in Telegram Web and look at the numeric value in the URL.

Pre-built image with yt-dlp and ffmpeg included:

docker run -d \ -v /path/to/config.toml:/app/config.toml \ -v /path/to/data:/data \ -e CONFIG_PATH=/app/config.toml \ -e RUST_LOG=info \ rainevi/tgreddit

Image available at rainevi/tgreddit for both linux/amd64 and linux/arm64.

Example setup for running on a Linux server or Raspberry Pi.

1. Install tgreddit and runtime dependencies:

   curl -fsSL https://raw.githubusercontent.com/raine/tgreddit/master/scripts/install.sh | bash sudo apt install -y ffmpeg python3 sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp sudo chmod a+rx /usr/local/bin/yt-dlp

2. Create a dedicated user and directories:

   sudo useradd -r -s /usr/sbin/nologin tgreddit sudo mkdir -p /opt/tgreddit /var/lib/tgreddit sudo chown tgreddit:tgreddit /var/lib/tgreddit sudo cp "$(which tgreddit)" /opt/tgreddit/tgreddit sudo cp config.example.toml /opt/tgreddit/config.toml # Edit /opt/tgreddit/config.toml with your settings

3. Create /etc/systemd/system/tgreddit.service:

   [Unit] Description=tgreddit Documentation=https://github.com/raine/tgreddit After=network-online.target Wants=network-online.target [Service] Type=simple User=tgreddit Group=tgreddit WorkingDirectory=/opt/tgreddit Environment=CONFIG_PATH=/opt/tgreddit/config.toml Environment=RUST_LOG=info ExecStart=/opt/tgreddit/tgreddit Restart=on-failure RestartSec=5 NoNewPrivileges=yes ProtectSystem=strict ProtectHome=yes PrivateTmp=yes ReadWritePaths=/var/lib/tgreddit RestrictSUIDSGID=yes ProtectKernelTunables=yes ProtectControlGroups=yes DevicePolicy=closed RestrictRealtime=yes LockPersonality=yes StandardOutput=journal StandardError=journal SyslogIdentifier=tgreddit [Install] WantedBy=multi-user.target

4. Enable and start:

   sudo systemctl daemon-reload sudo systemctl enable --now tgreddit sudo journalctl -u tgreddit -f # follow logs

The project uses just, direnv and entr.

just dev