gramsrv is an open-source Telegram-like MTProto server written in Go. It is
built for real client compatibility, self-hosted chat experiments, protocol
research, and long-running work toward a practical community server.
Website · Discussion group · Channel · 中文 README
gramsrv is independent and unofficial. It is not affiliated with, endorsed by,
or sponsored by Telegram or the official Telegram team.
telesrv-demo-split-60s.mp4
| Status | Trait | What it means |
|---|---|---|
| ✅ | One program startup | One Go binary prepares RSA keys, runs migrations, seeds data, opens MTProto, serves RPC handlers, dispatches updates, and starts workers. |
| ✅ | Fully open server code | Protocol edge, domain services, storage, compatibility handlers, media, updates, admin surfaces, and experiments are all in this repository. |
Everything below is an implemented server-side capability in the open-source codebase.
| Status | Feature | What works today |
|---|---|---|
| ✅ | MTProto server edge | TCP transport, RSA key exchange, auth keys, encrypted sessions, salts, ack/resend, bad messages, RPC dispatch, and layer compatibility helpers. |
| ✅ | Login and accounts | Development login code, sign-in, sign-up, log-out, authorizations, account settings, SRP/password state, email/passkey-oriented paths. |
| ✅ | Users and contacts | User profiles, usernames, profile photos, contact import/search, blocked/privacy state, presence, and last-seen style status. |
| ✅ | Dialogs and sync | Dialog list, pinned dialogs, manual unread, folders/filters, drafts, read boundaries, durable updates, online fan-out, and offline difference recovery. |
| ✅ | Private chats | Send, history, read receipts, edit, delete, forward, reply, rich entities, grouped/media messages, reactions, scheduled/TTL-oriented paths. |
| ✅ | Supergroups and channels | Create, join, leave, invite links, participants, admins, forum topics, history, send/edit/delete/read, reactions, public search, and previews. |
| ✅ | Media and files | Upload, download, local blob storage, photos, documents, thumbnails, external media fetch, web page previews, map tile cache hooks, profile/channel photos. |
| ✅ | Stickers and reactions | Sticker/reaction catalog, seed support, recent reactions, top reactions, default reactions, and moderation-oriented reaction paths. |
| ✅ | Gifts and stars | Star gifts and local stars ledger foundations for compatibility and future feature work. |
| ✅ | Bots and mini apps | Bot service foundations, callbacks, inline helpers, webview/mini-app paths, minimal Bot API gateway, and demo tools. |
| ✅ | Calls and real-time | Private call signaling foundations, group call state, SFU/TURN building blocks, liveness, and expiry workers. |
| ✅ | Admin and operations | Admin API/UI backend, PostgreSQL migrations, Redis volatile state, retention workers, pprof/debug hooks, and load-test helpers. |
| ✅ | Desktop, Android, and Web focus | Telegram Desktop is the primary target, with Android and Web compatibility paths actively covered by the same server. |
Some items are compatibility-first or experimental, but they are real open server code, not hidden product-only features. The next step is making these paths stronger together.
Requirements:
- Go 1.25 or newer
- Docker Desktop or Docker Engine with Compose
- OpenSSL, if you want to build a matching Telegram Desktop client
Start PostgreSQL and Redis:
docker compose -f deploy/docker-compose.yml up -dBuild and run the single server program:
go build -o bin/gramsrv.exe ./cmd/telesrv
.\bin\gramsrv.exeOn first start, gramsrv creates data/server_rsa.pem, applies database
migrations, seeds bundled language packs, prepares optional media resources,
starts MTProto on 0.0.0.0:2398, and brings up the update/media/background
workers in the same process.
Useful local environment variables:
| Variable | Default | Meaning |
|---|---|---|
TELESRV_LISTEN |
0.0.0.0:2398 |
MTProto listen address |
TELESRV_ADVERTISE_IP |
127.0.0.1 |
IP advertised to compatible clients |
TELESRV_DC |
2 |
self-hosted DC id |
TELESRV_DEV_AUTH_CODE |
12345 |
fixed login code for local development |
TELESRV_POSTGRES_DSN |
local Compose DSN | PostgreSQL connection string |
TELESRV_REDIS_ADDR |
127.0.0.1:6399 |
Redis address |
TELESRV_LANGPACK_SEED_DIR |
data/langpack |
bundled language pack seed directory |
TELESRV_BLOB_DIR |
data/blobs |
local media blob directory |
TELESRV_STICKER_SEED_DIR |
data/sticker-seed |
optional sticker/reaction seed directory |
The optional sticker seed directory is skipped when it does not exist.
Stock Telegram clients will not connect to gramsrv because they trust
Telegram's production DC list and RSA keys. Use a patched experience client from
the official website, or build your own client with a
minimal protocol patch.
Current Telegram Desktop baseline:
- Telegram Desktop commit:
9caf32dffc90ddd9bb08ad5777b865f729fa167b - TL layer: 227
- Local DC:
127.0.0.1:2398, DC id2
After gramsrv generates data/server_rsa.pem, export the matching public key:
openssl rsa -in data/server_rsa.pem -RSAPublicKey_out -out data/server_rsa.pubPatch Telegram/SourceFiles/mtproto/mtproto_dc_options.cpp:
- Replace the built-in production/test DC lists with your
gramsrvendpoint. - Replace both
kPublicRSAKeysandkTestPublicRSAKeyswithdata/server_rsa.pub. - Add
Flag::f_tcpo_onlyto the built-in DC flags.
Keep the client patch minimal: endpoint, RSA key, and TCP-only flags only.
Use separate client working directories so sessions do not share local tdata:
$tdesktop = "C:\path\to\tdesktop\out\Debug\Telegram.exe"
Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-alice")
Start-Process $tdesktop -ArgumentList @("-workdir", "$PWD\.tdata-bob")Log in with different phone numbers. In local development, the login code is
12345 unless you changed TELESRV_DEV_AUTH_CODE.
Recommended checks:
- Send private messages, stickers, media, replies, forwards, edits, deletes, and read receipts between two users.
- Keep one device online and restart another device to verify offline
updates.getDifferencerecovery. - Open the same account from multiple sessions and confirm current-session echoes are not duplicated while other online sessions receive updates.
- Check server logs for no new
NOT_IMPLEMENTED,Unhandled RPC,bad_msg, panic, or internal errors.
cmd/telesrv/ server entrypoint
cmd/telesrv-admin/ admin backend and web UI
deploy/ docker-compose, migrations, deploy helpers
data/ bundled language packs and optional seed data
internal/mtprotoedge/ MTProto transport, auth key, session, ack/resend
internal/rpc/ TL router and client compatibility handlers
internal/app/ domain services
internal/domain/ protocol-independent domain models
internal/store/ memory/postgres/redis storage backends
internal/seed/ bundled seed catalog loaders
internal/sfu/ real-time SFU experiments
internal/turnsrv/ TURN/STUN building blocks
gramsrv will get better fastest if more people run it, break it, profile it,
and send focused improvements. Helpful contributions include:
- Telegram Desktop and Android compatibility reports with reproducible steps.
- RPC traces for startup, sync, chat, media, calls, bots, or edge cases.
- Focused fixes for implemented paths instead of broad rewrites.
- Tests for online/offline updates, multi-device sessions, read state, media, and channel behavior.
- Performance work on hot paths such as fan-out, pagination, storage queries, media upload/download, and connection handling.
- Setup improvements that make the one-program local experience smoother.
If a change affects visible client behavior, please include the client
version/commit, the RPC path you tested, and whether server logs stayed free of
new NOT_IMPLEMENTED, Unhandled RPC, bad_msg, panic, or internal errors.
gramsrv is released under the Apache License 2.0. You may use,
modify, distribute, and use it commercially under the terms of Apache-2.0.
For paid custom development, you can contact the author through the discussion group or website. Custom work can cover server features, Telegram Desktop, Android, Web, deployment, compatibility adaptation, or other client/server paths around this project.