Skip to main content
Telegram gives you a remote control for Max that works from anywhere. You can send tasks while away from your machine, dispatch background coding jobs, and receive notifications when workers finish — all from your phone.
1

Create a bot via @BotFather

  1. Open Telegram and search for @BotFather.
  2. Send /newbot and follow the prompts (choose a name and username for your bot).
  3. Copy the bot token BotFather gives you — it looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.
2

Get your Telegram user ID

  1. Search for @userinfobot on Telegram.
  2. Send it any message.
  3. It replies with your numeric user ID (for example, 123456789).
Max uses your user ID to lock the bot to you exclusively. Without it, anyone who discovers your bot’s username could send it commands.
3

Run max setup

Run the interactive wizard and enter the token and user ID when prompted:
max setup
Alternatively, edit ~/.max/.env directly:
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
AUTHORIZED_USER_ID=123456789
4

Disable group joins (recommended)

Prevent your bot from being added to group chats:
  1. Go back to @BotFather.
  2. Send /mybots and select your bot.
  3. Open Bot Settings → Allow Groups?
  4. Set to Disable.
This is an extra layer of protection — even if someone adds your bot to a group, Max will silently ignore all messages from users whose ID does not match your AUTHORIZED_USER_ID.
5

Start Max and test

Start the daemon:
max start
Open Telegram, find your bot, and send it a message. Max should reply within a few seconds. If you see the “typing…” indicator appear, the bot is connected.

​
Available bot commands

CommandWhat it does
/cancelCancel the current in-flight message
/modelShow the current model
/model <name>Switch to a different model
/autoToggle automatic model routing on or off
/memoryList stored memories
/skillsList installed skills
/workersList active worker sessions
/restartRestart the Max daemon
/helpShow the full command list

​
Security model

Max’s Telegram integration is locked to a single authorized user ID. The auth check happens at the grammy middleware layer — messages from any other Telegram user ID are silently dropped before they reach the orchestrator. There is no way to escalate access by adding the bot to a group or sending commands from a different account. The bot token and authorized user ID are stored in ~/.max/.env on your local machine and are never sent anywhere beyond Telegram’s API.

​
Troubleshooting

  • Confirm Max is running: max tui should connect successfully.
  • Check that TELEGRAM_BOT_TOKEN and AUTHORIZED_USER_ID are set in ~/.max/.env.
  • Run max setup to re-enter the token if you’re unsure it’s correct.
  • Make sure the user ID in .env matches the number @userinfobot returned for your account.
The bot token is invalid or has been revoked. Go to @BotFather, generate a new token for your bot, and update TELEGRAM_BOT_TOKEN in ~/.max/.env or re-run max setup.
Another instance of Max is already running with the same token. Run pkill -f 'max start' to stop any stale processes, then start Max again.
The message is probably being dropped by the auth middleware. Confirm that the number in AUTHORIZED_USER_ID exactly matches the ID @userinfobot gave you — they must be identical. There is no partial match or fallback.
Telegram has a 4,096 character per-message limit. Max automatically chunks long responses into multiple messages, so a very long reply will arrive as a sequence of messages rather than one block.

Build docs developers (and LLMs) love

Get started for freeTalk to us