# TgWitness Setup: Windows, Linux, macOS & Docker

Canonical page: https://phishdestroy.io/tgwitness/docs/reference/quickstart/

Choose a TgWitness installation method, launch the panel and check your first workspace. Includes Windows, Linux, macOS, Docker and the synthetic demo.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2)

**English** · [Русский](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/QUICKSTART.md) · [Українська](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/QUICKSTART.md) · [Español](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/QUICKSTART.md) · [Português (Brasil)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/QUICKSTART.md) · [Türkçe](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/QUICKSTART.md) · [العربية](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/QUICKSTART.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/QUICKSTART.md) · [اردو](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/QUICKSTART.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/QUICKSTART.md) · [Bahasa Indonesia](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/QUICKSTART.md) · [Tiếng Việt](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/QUICKSTART.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/QUICKSTART.md)

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](https://phishdestroy.io/tgwitness/docs/reference/quickstart/#explore-the-interface) before connecting an account. [Choose a guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) for proxies, witnesses, exports or server setup. [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) (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](https://phishdestroy.io/tgwitness/docs/reference/installation/) 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`](https://github.com/phishdestroy/TgWitness/archive/refs/heads/main.zip) 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](https://phishdestroy.io/tgwitness/docs/reference/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](https://phishdestroy.io/tgwitness/docs/reference/settings/). 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](https://phishdestroy.io/tgwitness/docs/reference/panel/) 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](https://phishdestroy.io/tgwitness/docs/reference/accounts/): 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](https://phishdestroy.io/tgwitness/docs/reference/accounts/#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](https://phishdestroy.io/tgwitness/docs/reference/timestamp/) 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](https://phishdestroy.io/tgwitness/docs/reference/connection/) 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](https://phishdestroy.io/tgwitness/docs/reference/collection/) 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](https://phishdestroy.io/tgwitness/docs/reference/operations/) for backup/restore, [DEPLOYMENT.md](https://phishdestroy.io/tgwitness/docs/reference/deployment/) for hosting, and [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) 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](https://phishdestroy.io/tgwitness/docs/reference/verification/) and [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md).
