Docs
Security and privacy
Dotiphant stores your archive in a private folder on your computer and your Telegram session and keys in the system keychain. It only reads from Telegram. The viewer listens on 127.0.0.1 only, and the MCP server listens on 127.0.0.1 unless you start it with --allow-remote.
When you ask an AI app a question, the messages it reads go to that app's provider. Two commands and one deleted folder remove everything.
What is stored where
| What | Where |
|---|---|
| Messages, chat names, sender names | dotiphant.db, a SQLite file in the data folder |
| Downloaded photos and files | media/ in the data folder, only for chats where you asked for media |
| Your choices | settings.json in the data folder |
| Approved remote apps, hashed tokens, open approval requests, pairing code | oauth.json in the data folder, readable only by you |
| Sync progress | status.json and logs/ in the data folder. These never contain message text, phone numbers or secrets |
| Telegram API id and hash, login session, HTTP MCP token, viewer key | The system keychain, under "Dotiphant (unofficial Telegram archive)" |
The data folder is ~/Library/Application Support/Dotiphant on macOS, ~/.local/share/dotiphant on Linux and %APPDATA%\Dotiphant on Windows, or whatever DOTIPHANT_HOME points to. It is created readable only by your user account. dotiphant status prints the exact path.
On a computer without a keychain (for example a headless Linux server), secrets go to secrets/ in the data folder as files only your user can read. Set DOTIPHANT_SECRETS=file to always use these files, for example in a container. dotiphant status shows which one is in use.
The archive itself is not encrypted beyond what your disk encryption provides. Turn on FileVault (macOS), BitLocker (Windows) or full-disk encryption (Linux).
The session is your account
The Telegram session that Dotiphant stores gives full access to your Telegram account, the same as a logged-in Telegram Desktop. Anyone who can read your keychain or your user account can use it. Protect your computer like you protect your phone: a login password, screen lock and disk encryption.
You can see and end the session at any time in the Telegram app under Settings > Devices. It shows up as "Dotiphant".
A login belongs to the API id and hash that made it. When you replace them (dotiphant setup --new-credentials, other values in dotiphant setup, or new values on /setup), Dotiphant first tries to end the old session on Telegram, so old entries do not pile up under Settings > Devices. If Telegram cannot be reached, it says so; end the old entry there by hand.
Read-only toward Telegram
Dotiphant only reads. It never sends, edits, deletes, forwards or reacts to messages, never joins or leaves chats and never marks messages as read. Requests are paced and Dotiphant waits whenever Telegram asks it to slow down.
Syncing never deletes messages from the archive. When a sync sees that a message was edited, Dotiphant keeps the earlier text too. A sync looks for edits in a chat's latest 100 messages, when the chat has new messages or when you sync it on its own (dotiphant sync CHAT, or Refresh chat in the viewer). Edits to older messages are not fetched. To remove a chat on purpose, for example when someone asks you to delete their messages, run dotiphant forget CHAT. It deletes the chat, its messages and its media from the archive and stops syncing it.
Verify a download
Dotiphant holds your Telegram session, so check that what you install is what the project released. Each GitHub release has three files:
dotiphant-X.Y.Z-py3-none-any.whl, the wheel that gets installed.dotiphant-X.Y.Z.tar.gz, the source archive.SHA256SUMS, the SHA-256 checksums of the other two.
The installer (install.sh, worth reading first) checks the wheel for you. It downloads the wheel and SHA256SUMS from the same release, compares them and prints the hash. On a mismatch or a missing file it stops and installs nothing. If the GitHub CLI (gh) is installed and logged in, it also runs the attestation check below and reports the result.
Check the checksum by hand
Download the wheel and SHA256SUMS from the release page into one folder. In that folder, run:
shasum -a 256 -c --ignore-missing SHA256SUMS # macOSsha256sum -c --ignore-missing SHA256SUMS # LinuxEach file you downloaded should show OK. Then install the file with uv tool install ./dotiphant-X.Y.Z-py3-none-any.whl. A checksum from the same release page catches a broken or swapped download. It cannot prove who built the file: anyone who can change the release can change both.
Check the build attestation
Each release also has a signed build attestation (SLSA build provenance) for the wheel, the source archive and SHA256SUMS. GitHub Actions creates it while it builds the files. It records which repository, workflow and commit produced each file, and it is signed with Sigstore. Check it with the GitHub CLI:
gh auth login # oncegh attestation verify dotiphant-X.Y.Z-py3-none-any.whl --repo Zierold-Ventures/dotiphantA passing check means the file was built by the release workflow of Zierold-Ventures/dotiphant and has not changed since.
Who can reach the archive
The viewer
dotiphant openlistens on 127.0.0.1, so only programs on your computer can reach it. It also needs a private key, so other programs and other user accounts on the same computer cannot read the archive.dotiphant openopens a link with the key once; the viewer swaps it for a browser cookie and removes it from the address bar. The cookie holds a random session value, not the key. It works only as a cookie and stops working when the viewer stops; the nextdotiphant openstarts a new session.dotiphant open --no-browserprints the link instead. Scripts can send the key asAuthorization: Bearer KEY. The key is created on first use and kept in the keychain asviewer_token.- The viewer accepts changes (refresh, favorites) from a browser only from its own pages: every
/api/request and every POST must carry the page token that each viewer page holds, in addition to the cookie. The page token protects against other web pages open in your browser. It does not protect against programs: a program that has the cookie can load a viewer page and read the page token from it. - The browser setup at
/setupfollows the same rules. It needs the key, accepts changes only from its own pages, never sends the API hash back to the page, keeps the two-step password and login code in memory only until Telegram has checked them, limits login attempts, and is off in the demo. - Anyone who captures the viewer cookie can read the archive and make changes until the viewer stops. Browsers send cookies for 127.0.0.1 to every port on 127.0.0.1, so on a computer shared with other people, another user's program listening on another port could receive your viewer cookie when your browser visits it. The cookie never reveals the viewer key, and it cannot stop the viewer. Use the viewer on a computer that only you use, and stop it (Ctrl+C or
dotiphant stop) when you are done.
The MCP server
- The MCP server normally runs over stdio: your AI app starts it as a child process and nothing listens on the network.
dotiphant mcp --httplistens on 127.0.0.1 and requires a token on every request. Apps that support OAuth (ChatGPT, claude.ai) get their own token after you approve them. Approved apps and hashed tokens are kept inoauth.json;dotiphant mcp --clientslists them anddotiphant mcp --revokeremoves them.- Apps that can set headers can use the static bearer token instead, created on first use and kept in the keychain;
dotiphant mcp --show-tokenprints it. Anyone with a valid token can read your whole archive. --public-urlis for an HTTPS tunnel you run; see Remote access.--allow-remotelets other machines connect directly; use it only on a network you control.
Approving remote apps
Anyone who finds your tunnel URL can register an app and open an approval page. Only you can approve it, in one of two ways:
- In a terminal (safer): the page shows a command like
dotiphant mcp --approve K7QM-2XPA. It prints the app name and the exact address your browser returns to, and asks y/N. It needs an interactive terminal. Then choose Continue on the page. - With the pairing code that only your terminal shows (
dotiphant mcp --pair). It has 8 digits, works once and expires after 30 minutes.
The page shows the full return address of this request, with its host highlighted. The authorization goes to that address, so approve only if the host belongs to the app you are connecting right now. The app name is chosen by the app and proves nothing.
Limits that keep strangers out without locking you out
- Return addresses must use
https://, orhttp://on 127.0.0.1, localhost or [::1]. Addresses with a user name (user@host) or a fragment (#...) and other schemes such asjavascript:ordata:are refused. An app may register at most 5 addresses of up to 500 characters, and a name of up to 100 characters. Other metadata such as logos is not stored or shown. Oversized requests are refused. - Five wrong pairing codes close that one approval request. After 20 wrong codes within 10 minutes, code entry pauses for 10 minutes for everyone. Terminal approval keeps working during the pause. At most about 40 guesses fit into one code's lifetime, out of 100 million possible codes.
- At most 50 unapproved apps and 50 open approval requests are kept. A flood of new ones pushes out the oldest, so it cannot block a real app for long. It can push out a request you just started; start connecting again if the page says the link expired.
- Every refresh replaces the app's tokens. If an old refresh token is ever used again, Dotiphant assumes it was copied and revokes every token of that approval. The app then has to be approved again.
oauth.jsonis changed under a file lock, sodotiphant mcp --revokeand a running server never overwrite each other.
Remaining risks: if you approve a request without checking the return address, the app at that address gets read access. A stranger can also keep pausing code entry; use terminal approval then.
What an AI app receives
When you ask an AI app a question, it calls Dotiphant's tools and receives the matching messages: text, sender names, chat names and dates. The app then sends that content to its provider (Anthropic, OpenAI, Cursor and so on) to answer you, under that provider's privacy terms. Dotiphant cannot control what happens after that. Only connect apps whose provider you trust with your chats.
All tools are read-only. The one exception is refresh, which runs a sync to fetch new messages; it still only reads from Telegram. refresh does not start a new sync within 60 seconds of the last one; it reports the last result and when the next refresh is allowed. This keeps a looping or tricked AI app from hammering Telegram.
Prompt injection
Anyone who can message you can put text like "ignore previous instructions" into your archive. Dotiphant marks every message it hands to an AI as untrusted content and tells the AI not to follow instructions inside it. The marker lines use runs of three < or >; any such run inside a message is spaced out, so a message cannot fake the end of the untrusted block.
This lowers the risk but does not remove it, because the AI model makes the final decision. Since Dotiphant's tools cannot send messages or change anything, a tricked AI still cannot act in Telegram through Dotiphant. Be careful when the same AI app also has tools that can send email, run commands or move money.
Choose which chats AI apps can read
You decide which chats your AI may read. Hide any chat from AI apps with dotiphant ai hide CHAT, or the toggle in the viewer, or switch to dotiphant ai mode selected to share only the chats you choose.
Your responsibilities toward the people you chat with
Your archive holds other people's messages. They did not choose to use Dotiphant. Before you connect an AI app, hide the chats that should stay out of it (see above).
- Keep the archive for your own use. Do not publish it, sell it or share it with people who were not in the conversation.
- Before you connect an AI app, check how its provider handles your data. Some consumer plans may use conversations to improve their models unless you opt out.
- Be careful with sensitive topics, such as health, politics, religion or money. Only send them to an AI app if you would be comfortable forwarding the messages yourself.
- If someone asks you to delete their messages, honor it with
dotiphant forget CHAT. - If you use Dotiphant for work, data protection law (such as the GDPR in the EU) likely applies in full. Ask your data protection officer before you start.
The full app privacy notice is on GitHub.
Wiping everything
dotiphant schedule remove # stop background refreshdotiphant logout --forget-credentials # end the session on Telegram, remove every stored secret--forget-credentials removes the session, the API id and hash, the viewer key, the MCP token and the approved remote apps (oauth.json). If Telegram cannot be reached, the command says so: end the session in the Telegram app under Settings > Devices. Running viewers and a running dotiphant mcp --http check the stored keys every few seconds. Within a few seconds of the command, they stop accepting the old keys and tokens, on any port, and a viewer shuts down at its next request. The one exception is a token passed with --token: it works until you stop that server.
Then delete the data folder (the path is shown by dotiphant status). If you tried dotiphant demo, also delete the demo folder next to it ("Dotiphant Demo", or "dotiphant-demo" on Linux). To remove Dotiphant from your AI apps, delete the dotiphant entry from their MCP settings, or for Claude Code run claude mcp remove dotiphant. Finally, run uv tool uninstall dotiphant (or pipx uninstall dotiphant).
Messages that AI apps already read stay with their providers. Delete those conversations in each app if you want them gone.
Telegram terms
Dotiphant uses the public Telegram API with API credentials that you create yourself, so you are the developer of record under the Telegram API Terms of Service. In practice:
- Use it for your own account and your own chats.
- Dotiphant does not train AI models. Using Telegram data with AI apps is subject to the Telegram API Terms of Service and the Terms for Content Licensing and AI Scraping. Check them before you connect an AI app; you are responsible for how you use your archive.
- Do not present Dotiphant or anything built on it as an official Telegram app.
Dotiphant is an independent, unofficial project. It is not affiliated with Telegram.
Install Dotiphant
Free and open source (MIT). macOS and Linux; Windows experimental. The command installs the latest GitHub release and opens the setup in your browser. It takes about five minutes.
The script is about 150 lines. Read it first, or see other ways to install. The installer verifies the download against the release checksums (SHA256SUMS) before installing. You can check signed build provenance with gh attestation verify; see Verify a download.
curl -fsSL https://dotiphant.com/install.sh | shdotiphant open # setup opens in your browser