gramsrv

Own the server. Speak MTProto. Use real Telegram clients.

gramsrv is an open-source Telegram-compatible server and MTProto backend written in Go. It is built for self-hosted networks, protocol research, and community-driven chat systems that need real client compatibility—not just a Telegram-like interface.

Website · OwpenGram client · Discussion group · Channel · 中文 README

Quick start on macOS/Linux (v2)

Install Git and Docker Desktop (or Docker Engine with Compose v2), start Docker, then run:

git clone --branch v2 --single-branch https://github.com/iamxvbaba/gramsrv.git
cd gramsrv
./scripts/start-docker.sh

That is all a local first run needs. The script creates deploy/docker/.env, anonymously pulls the seven ready-to-run v2 images from ghcr.io/iamxvbaba/gramsrv, starts PostgreSQL, Redis, Migrate, File, Core, Egress, SFU, Admin, and Edge in dependency order, and waits until the stack is ready. No local Go toolchain, PostgreSQL, Redis, image build, or docker login is required.

• The development login code is 12345.
• The default listener is restricted to 127.0.0.1 for a client on the same computer.
• The generated stack enables RTMP ingest and IPv4 TURN. For remote use, allow and forward 2400/tcp, 12400/udp, and 12500-12999/udp in addition to the client and SFU ports; the startup script prints the configured endpoints. The v2 Compose file already publishes these ports from .env, so no manual compose.yaml edit is needed.
• The matching public test key is deploy/docker/assets/test-server-rsa.pub.
• Accounts, database state, media, Redis state, and the RSA identity are stored in Docker named volumes and survive container recreation and a normal Compose shutdown. Do not use Compose down -v unless you intend to erase them.
• Run without --build to use the published images. --build is only for validating local source changes.

For a temporary LAN experience, replace the example address with the Docker host's LAN address:

./scripts/start-docker.sh \
  --advertise-ip 192.168.1.20 \
  --public-base-url http://192.168.1.20:2401 \
  --public-web-base-url http://192.168.1.20:2401 \
  --allow-insecure-development-auth

Stock Telegram clients cannot connect without an endpoint and RSA-key patch; use a compatible client from the project website. See the Docker deployment runbook for firewall, backup, upgrade, remote access, and production guidance.

Why gramsrv

Most Telegram clones reproduce the interface. gramsrv implements the server side of the protocol so compatible clients can communicate through infrastructure you control.

• Real MTProto transport, authentication, encrypted sessions, RPC dispatch, updates, and multi-device synchronization.
• A practical feature surface covering chats, channels, media, reactions, gifts, bots, calls, and administration.
• Open server code from the protocol edge to business services, storage, and realtime media.
• A Go codebase designed for compatibility work, experimentation, and long-term community development.

The protocol stack is built on the published github.com/iamxvbaba/td module and follows current Telegram Desktop wire behavior.

Choose your architecture

Branch	Architecture	Best fit
main	Monolith	A straightforward single-process server for development, evaluation, and smaller deployments.
v2	Microservices	A split runtime with independent service boundaries for scaling, reliability, and production-oriented operation.

v2 at a glance

%%{init: {"theme":"neutral","flowchart":{"curve":"basis","nodeSpacing":32,"rankSpacing":48}}}%%
flowchart LR
  Clients["Telegram clients<br/>Desktop · Android · iOS · Web"]
  Edge["Edge<br/>MTProto · sessions"]
  Core["Core<br/>business RPCs"]
  Egress["Egress<br/>durable delivery"]
  FileData["FileData<br/>media bytes"]
  SFU["SFU<br/>realtime media"]
  Postgres[("PostgreSQL<br/>state · outbox")]
  Redis[("Redis<br/>location · push · control")]
  Blob[("Blob storage")]

  Clients <-->|MTProto| Edge
  Edge -->|"CoreExec gRPC<br/>TL bytes"| Core
  Core -->|"state + durable events"| Postgres
  Egress -->|"claim · project · ACK"| Postgres
  Egress -->|"bounded delivery"| Redis
  Redis -->|"push / control"| Edge
  Edge -->|"client ACK gRPC"| Egress
  Core -->|coordination| Redis
  Edge -->|FileData gRPC| FileData
  Core -->|FileData gRPC| FileData
  FileData --> Blob
  Core -->|SFU control| SFU
  SFU -->|"registry / ownership"| Redis
  Clients <-->|"voice · video"| SFU

Loading

Connections stay at the Edge, business execution stays in Core, and reliable delivery remains durable through Egress.

What works today

• Accounts, contacts, profiles, privacy, presence, and multiple sessions.
• Private chats, groups, supergroups, channels, topics, invites, and public links.
• Durable updates, dialogs, read state, drafts, reactions, offline recovery, and multi-device synchronization.
• Photos, documents, stickers, GIFs, voice messages, previews, uploads, and downloads.
• Gifts and Stars, Premium flows, bots and mini apps, translation, and AI compose integrations.
• Private-call signaling, group calls, RTMP live streams, and standalone SFU ownership.

Telegram Desktop is the primary compatibility target. Android, iOS, and Web client paths are also actively covered. Some advanced features remain compatibility-first or experimental, but the implementation is open in this repository.

Clients

Stock Telegram clients trust Telegram's production data centers and RSA keys, so they do not connect to private servers without a small endpoint and key patch. Use a compatible client from the project website or build your own patched client.

OwpenGram is a multi-server Telegram-style client with built-in support for gramsrv, private deployments, community nodes, and the official network from one client experience.

Build it with us

Compatibility reports, focused fixes, tests, and performance work are welcome. The most useful reports include the client version, reproducible steps, and the affected RPC or feature path.

Contributor: ajarshia — Android Persian (fa) language pack.

License and independence

gramsrv is released under the Apache License 2.0. It is independent and unofficial, and is not affiliated with, endorsed by, or sponsored by Telegram or its official team.