TgWitness / Documentation

Repository / docs/wiki/FAQ.md

Frequently asked questions

Straight to the answer. Accounts, capture, evidence and everyday operation.

05 · FIND AN ANSWER · All guides · Get help

On this page

What happens to messages deleted before collection started?#

Collection starts with what the account can see at that moment. History loading saves the current version of every visible message, a deletion notice for an earlier message is kept as a notice, and live observation keeps every later edit and deletion.

How is a message's Telegram origin established?#

Through the session it arrives on. Telegram delivers messages to every client, official apps included, over an MTProto session rather than with per-message signatures. The session key is negotiated against Telegram's pinned server key, and every update arrives encrypted and integrity-checked under it. TgWitness signs each observation into its journal as it arrives. GitHub Actions capture and Intel TDX deployments add attestation of the collector that received it. Where the messages come from

What does archive verification check?#

Record signatures, the journal chain, the file manifest and attachment hashes. Give it a key fingerprint and checkpoint kept elsewhere and it also checks the expected key and an earlier journal state. The minimum for evidence also needs time from a third party for the last record: a verified RFC 3161 or OpenTimestamps receipt, or a witness post read from t.me. A checkpoint alone is not enough, because the collector key signs it. A witness adds more checkpoints, and GitHub Actions capture also checks the archive's provenance against the approved workflow and collector version.

Verification steps · Technical trust model

How does TgWitness track event delivery?#

Each workspace records coverage: when observation ran, gaps after restarts or network drops, and their recovery. After a restart, missed updates are requested from the saved update position, and rechecks confirm saved messages. The coverage report shows exactly which periods the record speaks for. A witness probe with a second account checks that its answers arrive as live updates and records a gap when one shows up only in the chat history.

Which account does the collector use?#

A Telegram user account, which receives the same messages you see in the app. Bot tokens serve the optional witness.

Do I need my own API ID and API hash?#

The built-in pool works, and saved or imported credentials are reused. An API pair identifies the app; account access comes from the login. Each observation records whether a built-in public pair or your own pair was used. API pairs

Where are my Telegram sessions stored?#

In the workspace's encrypted vault on your own computer or server. The vault key is a file in the data directory unless a new installation uses an external master key, so protect that directory or the disk. The panel listens on localhost by default, and the application has no telemetry. Observe with a dedicated account.

How do I verify the installer before running it?#

Download the script with its signature and check both against the release key fingerprint with the verify-first commands. The download site is built by the public Installer workflow from the exact main revision, and the installer checks the SHA-256 and RSA signature of the package and dependency lock before installing.

Can several people have separate access permissions?#

Yes. Create a token under More tools → Access, pick workspaces, chats and permissions, add limits if you want. The main panel token stays unrestricted. See access and permissions.

Are messages and attachments encrypted on disk?#

Sessions, credentials and keys are encrypted in the vault. Protect the journal and files with disk encryption such as BitLocker, LUKS or FileVault; exports can carry an AES-256 password.

Does Lock stop collection?#

Lock closes the browser panel, and collection keeps running. Pause observation stops collecting; closing the tab leaves it running too.

Why can two accounts show different histories?#

Different access, join dates, visibility. Each workspace keeps its own observations and key, so always say which workspace a record came from.

Does a public proxy failure switch me to a direct connection?#

With Hide the address, collection waits for a working proxy. Direct as a last resort goes direct after a delay, and Server behind a tunnel or VPN allows direct. Outside requests and the witness have their own rules. See connection routes.

How do an evidence export and a backup differ?#

An export carries the records and verification material for a recipient and leaves out login and signing secrets. A backup is the whole stopped data directory plus any external vault key, for restoring the installation.

How independent is a witness?#

A witness has its own process and key and records checkpoints and rollback on any host. Run it on another host under another operator for full independence. The verifier checks the witness signature; the custodian's key-control record, kept with the key's fingerprint, shows who holds it. External time comes from Telegram's dates on the witness posts, read live from the public t.me page.

Which platforms are tested?#

Before each publication from main, CI authenticates the signed installer build and installs and checks it on Linux and Windows; pull requests that change the installer also run install.sh and install.ps1. The verification record lists live runs per platform and revision.

Where are the tests?#

The regression suite of 126 test modules runs in a private validation environment with synthetic accounts and a fake Telegram transport, so test files are not in Git. Public CI runs lint, dependency audits, wheel installs, installer signature checks, CodeQL, Trivy and verifier fuzzing. Tests and CI

How old is TgWitness?#

About six months of development and testing. The public repository was created on 29 October 2026 from the existing code, so its first commit already holds 658 files. Development history

How do I report a problem or contribute?#

Support for help and bugs, Contributing for code, Security for vulnerabilities.