Give agents a safe line to humans.

Run a local-first gateway.

The gateway defaults to loopback at http://127.0.0.1:8818. Use a dedicated Unix user and a per-agent key.

python3 -m venv .venv
. .venv/bin/activate
pip install agentforge-telegram-gateway==3.1.0

sudo agentforge-telegram-admin telegram-setup
sudo agentforge-telegram-admin telegram-doctor
sudo agentforge-telegram-admin provision my-agent \
  --output /var/lib/my-agent/telegram-gateway-key \
  --owner my-agent:my-agent
sudo agentforge-telegram-admin pair my-agent
sudo systemctl enable --now telegram-notifier
curl http://127.0.0.1:8818/health

There is no npm artifact for AgentRelay. The gateway, SDK, CLI and MCP client are shipped in the PyPI package.

Read events and send human-visible updates.

from agent_client import TelegramAgentClient

client = TelegramAgentClient.from_key_file(
    "my-agent",
    "/var/lib/my-agent/telegram-gateway-key",
)
print(client.inbox(limit=10))
client.notify("Deployment completed", title="Release")

TelegramAgentClient supports inbox, reply_text, reply_file, download and notify. Keep key files outside the repository and restrict their permissions.

Operate the gateway from automation.

agentforge-telegram --source my-agent \
  --key-file /var/lib/my-agent/telegram-gateway-key inbox --limit 10

agentforge-telegram --source my-agent \
  --key-file /var/lib/my-agent/telegram-gateway-key \
  notify --title "Deploy" --text "Production is healthy"

agentforge-telegram-admin telegram-doctor
agentforge-telegram-gateway

The admin binary handles setup, pairing, provisioning and diagnostics. The gateway binary starts the service.

Use simple authenticated HTTP operations.

curl -sS http://127.0.0.1:8818/v1/inbox?limit=10 \
  -H "Authorization: Bearer $AGENTRELAY_KEY"

curl -sS http://127.0.0.1:8818/v1/notify \
  -H "Authorization: Bearer $AGENTRELAY_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"Release","text":"Production is healthy"}'

Confirm the exact payload against the installed version before automating a production deployment.

Connect an MCP client to Telegram tools.

The Streamable HTTP endpoint is /mcp. URL-secret deployments expose /client/<secret>/mcp. OAuth discovery is available when enabled.

agentforge-telegram-mcp \
  --base-url https://telegram.example.com \
  --auth bearer \
  --key-file /var/lib/my-agent/telegram-gateway-key discover

agentforge-telegram-mcp \
  --base-url https://telegram.example.com \
  --auth bearer \
  --key-file /var/lib/my-agent/telegram-gateway-key tools

agentforge-telegram-mcp \
  --base-url https://telegram.example.com \
  --auth bearer \
  --key-file /var/lib/my-agent/telegram-gateway-key \
  call telegram_inbox --arguments '{"limit":10}'

The client supports bearer, URL-secret and OAuth modes and negotiates protocol versions 2026-07-28, 2025-11-25 and 2025-06-18.