TgWitness / Documentation

What has been tested →

Reference / Set up

TgWitness Setup: Windows, Linux, macOS & Docker

Every way to install and launch TgWitness: Windows package, Python, Docker and the synthetic demo, with first checks.

TgWitness / Documentation

Getting started

English · Русский · Українська · Español · Português (Brasil) · Türkçe · العربية · فارسی · اردو · हिन्दी · Bahasa Indonesia · Tiếng Việt · 简体中文

TgWitness is a standalone application for observing Telegram groups and channels that your accounts can access. It runs locally with its own data directory.

First visit? Explore the demo before connecting an account. Choose a guide for proxies, witnesses, exports or server setup. GitHub Actions capture (preview) runs a capture in your own GitHub fork instead of a local installation.

Install and start#

The guided installer includes its own Python and checks package hashes and release signatures before installing. Running it again updates an existing installation.

Linux / macOS:

curl -fsSL https://get.destroy.tools/install.sh | bash

Windows (PowerShell or Command Prompt):

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex"

On an Ubuntu server, run as root to install a background service; on a desktop, run as your normal user. On Ubuntu the installer prints the panel address and access key; on macOS and Windows the local panel opens in your browser. Continue at Connect Telegram below. Install, verify and update covers the server access choices, checking the script before running it, updates and removal.

Other methods#

GitHub releases, the source and Docker are alternatives to the installer. Portable downloads become available after a release build is published:

Host Nothing installed From source: Python 3.11+ Docker: Engine/Desktop with Compose 2.20+
Windows Extract TgWitness-<version>-windows-amd64-portable.zip from GitHub Releases, double-click TgWitness.cmd Double-click Start.cmd Double-click scripts\Docker.cmd
Linux / macOS — sh start.sh sh scripts/docker-start.sh

For the source methods, download and extract current main or clone the repository:

git clone https://github.com/phishdestroy/TgWitness.git
cd TgWitness

Start.cmd offers to install Python 3.12 for your Windows user if no suitable Python is found (winget, or the signed python.org installer). start.sh prints the exact install command for your Linux distribution or macOS if Python is missing. The first source launch creates .venv and installs dependencies automatically.

Docker builds the application and starts it in the background; host Python is unnecessary. scripts\Docker.cmd and scripts/docker-start.sh print the panel address and token when the container is healthy. The equivalent Docker commands on every supported host are:

docker compose up -d --build --wait
docker compose exec tgwitness cat /data/panel-token.txt

Open http://127.0.0.1:8787. Use the token printed by the Docker helper or the second Docker command, or read data/live/panel-token.txt for a portable or source installation. Continue at Connect Telegram below. Native and Docker installations use separate storage; starting Docker does not import an existing native journal.

For a server, deployment covers automatic HTTPS, restart, published images, updates, and backups.

Explore the interface#

  1. Run TgWitness-Demo.cmd in the portable package, scripts\Demo.cmd in a Windows source folder, or sh start.sh --demo on Linux/macOS. A source launch first creates .venv and installs dependencies.
  2. Open http://127.0.0.1:8787.
  3. The local demo opens the sample journal automatically. No token copy is needed for direct local access.

Demo messages are fictional. Demo mode cannot connect a real Telegram account.

Connect Telegram#

[!WARNING] Use dedicated accounts. Telegram can restrict or permanently ban accounts for request volumes it considers excessive, whatever the client. Connect accounts prepared for observation rather than personal or valuable ones, and create an API ID / hash on a dedicated account.

  1. If the native demo is running, stop it and run Start.cmd or sh start.sh. Otherwise, keep the live installation started above running.
  2. Use the panel token to sign in. A new workspace opens first setup. Choose Just download, Follow chats or Evidence for a case.
  3. Review the connection check. Configure your own proxy if needed; connection settings remain available after setup.
  4. At Connect Telegram, choose a phone number, a QR code, account files (TData, .session, StringSession, account JSON) or a complete authorization key. Complete the Telegram confirmation, code and two-step password when requested.
  5. Check the displayed account, choose the chats and review your settings. Finish from the final screen. For Just download, Start export starts a one-time export and opens Exports to show its progress; it does not enable continuous observation.

After setup, Chats → Choose changes the selected chats. Settings controls collection and files; More tools → Sources provides the detailed source list at Standard or Expert level. The panel guide describes the six main sections and their contextual controls.

API ID + Hash is optional: the workspace uses its saved or imported pair, or a working pair from the built-in pool. To use your own app, paste one API ID:API Hash pair into API ID. For Auth key, paste all 512 hexadecimal characters and select the supplied DC ID. User ID is optional and checked if entered.

API credentials identify your application; they do not authorize an account by themselves. Private groups need no public username, but your account must have access.

For existing accounts, see accounts and session formats: the panel accepts Telethon StringSession, Telethon/Pyrogram SQLite, single-account TData ZIP, and supported account JSON. Select a session and its companion JSON together, press Check files, then Connect account. QR login is also available with the same optional API settings. TDLib, bot sessions and CSV/JSON account inventories are unsupported.

For several accounts, use Accounts → Import accounts and select their supported session files. Companion JSON files are paired by basename; each imported account gets its own workspace. See bulk import and account groups.

To add another account, press + beside the account selector or use Accounts → Add account. Workspaces have separate sessions, journals, keys, sources and queues. Switching views leaves other collectors running. The same Telegram account cannot be assigned to two workspaces in this installation. There is no fixed number of workspaces; they share one process, so capacity depends on the machine.

The live panel token protects access to your Telegram authorizations and saved material; it is separate from Telegram API credentials. Only an explicitly started, directly accessed local demo gets automatic entry. A remote/proxied demo still uses data/demo/panel-token.txt.

Review and export#

  • Journal: search and filter observations by source and event type.
  • Select an event to inspect its original record, attribution and saved versions.
  • Edit details show the available before/after content. Deletion details show the last captured content, if any; an unknown actor remains unknown.
  • Exports: signed ZIP, JSONL, CSV and offline HTML.
  • Full chat export (Chats → Export chat, or Exports → Capture or export one chat): download one chat's entire visible history as a signed bundle with chat.json (Telegram-export style) and a readable chat.html. Private chats work when the account is a member. It is a current snapshot, not a reconstruction of deleted or previously edited messages. Verify a copy with python verify.py chat-export.zip --fingerprint TRUSTED_SHA256.
  • Save checkpoint: keep the signed journal boundary outside the collector.
  • Download signed run receipt: preserve the collector's program/version record.
  • Prepare timestamp request: prepare an offline request for a timestamp authority; follow TIMESTAMP.md to obtain and verify a response.
  • Verify journal: check event signatures and chain links. ZIP export also checks media.

Supported browsers save large exports directly to a chosen file. Other browsers buffer at most 128 MiB. While the server is running, the streaming CLI supports larger downloads without buffering the whole response:

python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip

For another workspace, add --profile ID using Exports → Workspace ID. For a remote server, add --url https://your-server. The default transfer limit is 5 GiB; --max-mib changes it. Signed ZIP content has a separate 4 GiB uncompressed verification limit by default (More tools → Parameters raises it; verify such archives with verify.py --max-gib N). Verify the archive using a trusted copy of the verifier, an independently retained key fingerprint and, for the minimum for evidence, the timestamp authority's root certificate (--tsa-ca).

Check the installation#

python start.py --setup-only
python start.py --check
python start.py --check --json

--check probes local dependencies, signing support, storage, key configuration and the listening address. It does not install anything or connect to Telegram. A busy port may mean another instance is running. Use a different --port or stop it first.

The launcher installs into .venv. Auxiliary python -m tgwitness... commands must use .venv\Scripts\python.exe on Windows or .venv/bin/python on Linux/macOS, unless that environment is already activated.

Sessions, protection and operation#

A closed, consistent Telethon SQLite .session can be converted locally with python -m tgwitness.sessions account.session --out account.tgwitness-session, then loaded in More tools → Account → Files. Direct file import and QR login are also available. See CONNECTION-SECURITY.md for login formats, SOCKS5, HTTP CONNECT, MTProxy and external master keys.

Pause observation stops collection. Lock only closes browser access. Closing a tab leaves the collector process running. Stopping the process interrupts collection; a history snapshot cannot reconstruct all missed edits or deletions. See how collection works for event policies, attachment queues, account isolation, and restart behavior.

Sessions and secrets are encrypted. Message content, media and exports require an encrypted disk or volume. Verify journal signatures against a trusted key and retain checkpoints separately. Review capture records, external time receipts and environment attestations for the selected collection mode.

Read OPERATIONS.md for backup/restore, DEPLOYMENT.md for hosting, and deploy/ for service examples. The installed panel also includes an offline setup guide at /guide.html.

Actual verification and remaining boundaries are recorded in VERIFICATION.md and READINESS.md.