Skip to content

PyPI and native Linux

This path runs one application process with SQLite and a private MTProto bot session. A separate Bot API server is not required.

1. Install

On Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y ffmpeg pipx
pipx ensurepath
export PATH="$HOME/.local/bin:$PATH"
pipx install "asmr-tg-backup[performance]"
asmr-tg-backup --version

The performance extra includes cryptg for faster MTProto uploads.

2. Prepare Telegram

Then run:

asmr-tg-backup setup

Keep the default MTProto direct upload option. Setup asks for the BotFather token, destination, and the user ID allowed to open /panel. It then creates:

  • ~/.config/asmr-tg-backup/config.toml
  • ~/.config/asmr-tg-backup/sources.toml
  • ~/.local/share/asmr-tg-backup/state.db

MTProto logs in the bot rather than a personal Telegram account. The session file appears in the data directory when the first media file is delivered.

3. Add Twitch credentials when needed

YouTube needs no additional provider credentials. Before adding a Twitch source, put the Twitch application values in the environment file used by the user service:

TWITCH_CLIENT_ID=replace-with-client-id
TWITCH_CLIENT_SECRET=replace-with-client-secret

chmod 600 ~/.config/asmr-tg-backup/env

The Twitch setup guide links to the developer console and explains the access-token alternative.

4. Install the background service

One command creates the systemd user unit for the current pipx/virtualenv, enables it, starts it, and enables boot-time user services:

asmr-tg-backup service install

The command is repeatable: it refreshes the unit generated by this application and restarts the worker, so run it again after a pipx upgrade.

For a non-default configuration, append --config /absolute/path/config.toml. Check the service and follow its logs with:

systemctl --user status asmr-tg-backup.service
journalctl --user -u asmr-tg-backup.service -f

To stop the service and remove its unit later:

asmr-tg-backup service uninstall

Uninstalling the unit keeps the configuration, environment file, SQLite database, downloads, and MTProto session. It also leaves user-level linger enabled because other user services may use it.

To run in the foreground instead:

asmr-tg-backup run \
  --config ~/.config/asmr-tg-backup/config.toml

5. Add a source

Send /panel to the bot and add one YouTube or Twitch source. The panel updates ~/.config/asmr-tg-backup/sources.toml and synchronizes the runtime database. For batch or complete-field changes, edit that file and run:

asmr-tg-backup sources validate \
  --config ~/.config/asmr-tg-backup/config.toml
asmr-tg-backup sources apply \
  --config ~/.config/asmr-tg-backup/config.toml

Confirm the first download and delivery from the panel or asmr-tg-backup status.

6. Update

The update keeps the current configuration and data, then regenerates the user service for the upgraded pipx environment. Stop the application and every local Bot API service included in the backup so their state stays consistent.

Back up all of ~/.config/asmr-tg-backup/ and ~/.local/share/asmr-tg-backup/. The configuration backup includes config.toml, sources.toml, the optional env, and—after one-command extension setup—config.extensions.toml plus private files below extensions/config/.

When the deployment uses the native local Bot API, also back up ~/.config/systemd/user/asmr-tg-backup-telegram-bot-api.service. Stop both services before copying their data:

systemctl --user stop asmr-tg-backup.service
systemctl --user stop asmr-tg-backup-telegram-bot-api.service  # local Bot API only

Upgrade and validate while the services remain stopped:

pipx upgrade asmr-tg-backup
asmr-tg-backup --version
asmr-tg-backup extensions doctor \
  --config ~/.config/asmr-tg-backup/config.toml
asmr-tg-backup sources validate \
  --config ~/.config/asmr-tg-backup/config.toml

If extensions doctor reports a missing or incompatible package, rerun extensions enable <slug> for a trusted catalog extension. Update a third-party extension through the same pipx environment and its documented installation method. Rerun both validations before continuing.

Start the local Bot API first when the deployment uses it, then refresh the application unit and start the worker:

systemctl --user start asmr-tg-backup-telegram-bot-api.service  # local Bot API only
asmr-tg-backup service install
systemctl --user status asmr-tg-backup.service

Other upload and build paths