Getting Started

Getting started

01 · START HERE · All guides · Get help

On this page

• 1. Choose an installation
• 2. Explore without an account
• 3. Start your real workspace
• 4. Check your installation

1. Choose an installation

Easiest is the one-line installer. Otherwise grab a release ZIP or clone the repo.

Method	Start	Requirements
Windows source	Double-click Start.cmd	Python 3.11+, the launcher offers to install it
Linux / macOS source	sh start.sh	Python 3.11+ with venv
Windows portable	Unpack the whole ZIP, open TgWitness.cmd	Python is inside
Docker	scripts\Docker.cmd or sh scripts/docker-start.sh	Docker with Compose 2.20+

The launcher makes its own .venv. Leave the console window open while it collects. Docker runs in the background.

2. Explore without an account

For source installations, run scripts\Demo.cmd on Windows or:

sh start.sh --demo

Portable: TgWitness-Demo.cmd. Open http://127.0.0.1:8787, the demo opens straight away with made-up chats.

Poke around Chats, Journal and Exports, switch language and theme, try Ctrl+K / ⌘K.

3. Start your real workspace

Stop the demo first (same port), then run Start.cmd, sh start.sh or TgWitness.cmd.

Installation	Panel token
Source or portable, default live directory	data/live/panel-token.txt
Source or portable with a custom data directory	panel-token.txt inside that directory
Docker	docker compose exec tgwitness cat /data/panel-token.txt

Open the panel, paste the token, then go to Accounts and Collection. Native and Docker installs don't share data.

4. Check your installation

From the source folder:

python start.py --check --json

Checks prerequisites without touching Telegram. No environment yet? python start.py --setup-only first. Other port: --port 8791.

python -m tgwitness… commands in this wiki need the project environment: activate .venv or call .venv\Scripts\python.exe / .venv/bin/python.

Next: Connect an account · Troubleshooting · Complete quick start