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.
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#
- Run TgWitness-Demo.cmd in the portable package, scripts\Demo.cmd in a Windows source
folder, or
sh start.sh --demoon Linux/macOS. A source launch first creates.venvand installs dependencies. - Open http://127.0.0.1:8787.
- 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.
- If the native demo is running, stop it and run Start.cmd or
sh start.sh. Otherwise, keep the live installation started above running. - Use the panel token to sign in. A new workspace opens first setup. Choose Just download, Follow chats or Evidence for a case.
- Review the connection check. Configure your own proxy if needed; connection settings remain available after setup.
- 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. - 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 readablechat.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 withpython 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.