Telegram Pi Gateway

Standalone local Telegram gateway for Pi SDK. It runs outside the Pi process, lets one authorized Telegram user select a project under WORK_DIR, and talks to Pi with that project as the current working directory.

Requirements

• Docker Desktop for the recommended run mode
• Bun for optional local development
• A Telegram bot token from BotFather
• Pi already configured locally (pi login/settings/extensions/skills)

Configuration

Set these variables in your shell profile (.zshrc, .bashrc) or process environment:

export TELEGRAM_BOT_TOKEN="123:bot-token"
export TELEGRAM_ALLOWED_USER_ID="123456789"
export WORK_DIR="/Users/you/Developer"
export DATA_DIR="./data" # optional

See env.example.

Create and configure the Telegram bot

Use Telegram's official @BotFather bot to create and manage your bot.

1. Create the bot

1. Open Telegram and start a chat with @BotFather.
2. Send /newbot.
3. Choose a display name, for example Pi Gateway.
4. Choose a username ending in bot, for example my_pi_gateway_bot.
5. BotFather returns an HTTP API token. Use that value as TELEGRAM_BOT_TOKEN.
6. Start a chat with your new bot and press Start.

Keep the bot token private. Anyone with the token can control your bot.

2. Get your Telegram user id

1. Open @userinfo in Telegram.
2. Copy your numeric Telegram user id.
3. Use that value as TELEGRAM_ALLOWED_USER_ID.

Only this Telegram user id can use the gateway.

3. Configure the bot profile in BotFather

Open @BotFather, send /mybots, select your bot, and configure these settings:

• Edit Bot → Edit Description (/setdescription): shown as "What can this bot do?" when a user opens the bot. Suggested text:

  Personal Telegram gateway for Pi coding-agent sessions. Select a local project and talk to Pi from Telegram.

• Edit Bot → Edit About (/setabouttext): short bot profile bio. Suggested text:

  Personal Pi coding-agent gateway.

• Edit Bot → Edit Commands (/setcommands): command menu shown by Telegram. Paste this list:

  start - Show help and start the bot
  help - Show available commands
  workdir - Show the configured work directory
  projects - Search local projects
  use - Select a project
  current - Show the active project
  reset - Reset the active Pi session
  sessions - List remembered project sessions
  resume - Recover the active project session

• Bot Settings → Allow Groups? (/setjoingroups): keep groups disabled if this is a personal bot.

• Bot Settings → Group Privacy (/setprivacy): keep privacy enabled unless you intentionally add the bot to groups and need it to read group messages.

• Optional: Edit Botpic (/setuserpic) to set a profile image.

4. Recover or rotate a lost BotFather token

If you lost the token or think it leaked:

1. Open @BotFather.
2. Send /mybots.
3. Select your bot.
4. Choose API Token.
5. Use the shown token, or choose Revoke current token to rotate it and generate a new one.
6. Update TELEGRAM_BOT_TOKEN in your .env or deployment environment.
7. Restart the gateway.

BotFather also supports the direct /token command for token management.

References: Telegram Bot Features, Telegram Bot Commands.

Install

This gateway runs outside Pi. Do not install it with pi install; install and run it as a normal background service.

From npm

Install Bun first, because the gateway executes TypeScript with Bun:

curl -fsSL https://bun.sh/install | bash

Then install the gateway globally:

npm install -g telegram-pi-gateway

Set the required environment variables, then run it in the foreground:

export TELEGRAM_BOT_TOKEN="123:bot-token"
export TELEGRAM_ALLOWED_USER_ID="123456789"
export WORK_DIR="/Users/you/Developer"
export DATA_DIR="$HOME/.telegram-pi-gateway/data"

telegram-pi-gateway

Run in background with PM2

PM2 is the recommended npm-based background runner:

npm install -g pm2
pm2 start telegram-pi-gateway --name telegram-pi-gateway --update-env
pm2 save

Useful PM2 commands:

pm2 logs telegram-pi-gateway
pm2 restart telegram-pi-gateway --update-env
pm2 stop telegram-pi-gateway

To start again after reboot, run the command printed by:

pm2 startup

and then:

pm2 save

From GitHub

git clone https://github.com/Mrthnx/telegram-pi-gateway.git
cd telegram-pi-gateway
bun install
bun start

For development with file watching:

bun dev

Recommended run mode: Docker

Docker remains a good run mode if you prefer a containerized long-running process.

Docker

Create a local .env file first:

cp env.example .env

Edit .env with your values:

TELEGRAM_BOT_TOKEN="123:bot-token"
TELEGRAM_ALLOWED_USER_ID="123456789"
WORK_DIR="/Users/you/Developer"
DATA_DIR="/app/data"

Build and start the container in the background. Source .env first because Docker volume paths are expanded by your shell, not by --env-file:

set -a && source .env && set +a
docker build -t telegram-pi-gateway .
docker run -d \
  --name telegram-pi-gateway \
  --restart unless-stopped \
  --env-file .env \
  -v "$WORK_DIR:$WORK_DIR" \
  -v "$PWD/data:/app/data" \
  -v "$HOME/.pi:$HOME/.pi" \
  -v "$HOME/.config:$HOME/.config" \
  telegram-pi-gateway

Useful commands:

# See logs
docker logs -f telegram-pi-gateway

# Stop it
docker stop telegram-pi-gateway

# Start it again
docker start telegram-pi-gateway

# Rebuild after code changes
docker stop telegram-pi-gateway && docker rm telegram-pi-gateway
docker build -t telegram-pi-gateway .

The container uses --restart unless-stopped, so it keeps running after the terminal closes and starts again after Docker restarts.

Docker needs access to your host Pi configuration, credentials, skills, and project folders, so the command mounts $HOME/.pi, $HOME/.config, and $WORK_DIR into the container.

Telegram commands

• /start / /help — help
• /workdir — show configured WORK_DIR
• /projects <query> — search projects
• /use <name-or-relative-path> — select one project
• /current — show active project
• /reset — reset active Pi session
• /sessions — list remembered project sessions
• /resume — warm up/recover the active project session

After selecting a project, send normal messages. The bot replies Trabajando... while Pi runs and then sends the answer, split across multiple Telegram messages if needed.

Photos

The bot accepts Telegram photos, downloads the largest available image into DATA_DIR/downloads, and prompts Pi with the local image path plus any caption. Full multimodal handling depends on the active Pi model/SDK support; if the model cannot inspect images, Pi should ask for a textual description.

Pi package gallery

This project is a standalone Pi SDK gateway, not an in-process Pi extension or plugin. It does not register Pi tools, commands, event handlers, prompts, skills, or themes through a pi package manifest.

The package keeps the pi-package npm keyword so it is eligible for discovery on pi.dev/packages, together with the repository, homepage, license, and public package metadata in package.json.

To appear on the package gallery, the package still needs to be published or indexed from an eligible package source. The GitHub repository alone is not enough for npm keyword discovery.

Security notes

• The Telegram token must never be sent through chat.
• Only TELEGRAM_ALLOWED_USER_ID can use the bot.
• Project paths are resolved under WORK_DIR.
• Heavy folders such as node_modules, .git, dist, build, .next, vendor, and caches are ignored during discovery.