Pi Bot

A personal assistant in Telegram or WhatsApp.

One container, one volume, no web panel. It runs on the pi.dev harness. You choose the model. Tools come from Composio, Executor, Upsy, or your own MCP gateway.

GitHub Install

Beta. Configuration and commands can still change between releases.

Install
# Nothing in .env is required to boot.
git clone https://github.com/forge-z/pi-bot.git
cd pi-bot
cp .env.example .env
docker compose up -d --build
# Gateway, models, and MCP. The service name is pi-bot.
docker compose exec pi-bot npm run setup

Values in .env are optional overrides. If the gateway is already running when you pair WhatsApp, read the QR from docker compose logs.

Chat on one side, tools on the other

  1. 01

    A message arrives on Telegram or WhatsApp. One gateway per install.

  2. 02

    Only the allow list gets an answer. Everyone else is ignored.

  3. 03

    Your text model runs the turn. An image model can read photos and an audio model can transcribe voice notes. Replies are text.

  4. 04

    Anything outside the chat goes through MCP tools you connect. A call that needs approval waits for you.

Settings, credentials, and conversations are SQLite files on the volume at /app/data. The image is read-only. The assistant has no shell, filesystem, or browser of its own.

Five steps, in the terminal

npm run setup edits one section at a time. Enter keeps a saved value. Secrets stay hidden. Save and back writes the section.

  1. Open the menu

    With the container up, run npm run setup. A fresh container stays healthy while it waits. The menu lists the gateway, text model, image model, audio model, and MCP platform.

    Terminal showing the npm run setup main menu: gateway, text model, image model, audio model, and MCP platform.
    The setup menu.
    Screenshot: setup main menu
  2. Choose a gateway

    Telegram or WhatsApp. Saving one turns the other off. An install that never chooses stays on Telegram.

    Telegram asks for the bot token and the numeric user ids allowed to talk to it.

    Terminal showing Setup gateway, with Telegram and WhatsApp as the two choices.
    One gateway per install.
    Screenshot: Setup gateway
  3. Link WhatsApp

    The owner's number, with country code. Extra numbers are optional. Then pair with a QR under Linked devices, or with a phone code. The session stays on the volume.

    Terminal showing the WhatsApp menu: allowed numbers, pair with QR, and pair with a phone code.
    Allowed numbers, then a QR or a pairing code.
    Screenshot: WhatsApp pairing
  4. Pick the models

    Text is any official pi-ai provider with an API key, or ChatGPT Plus/Pro sign-in with none. Image and audio models are optional.

    Terminal showing the Text model section, at the start of the provider list, including ChatGPT.
    Text model. Setup stops before an external login.
    Screenshot: Text model
  5. Connect tools

    MCP platform: Composio, Executor, Upsy, a self-hosted gateway, Executor plus Composio, or none. Save and restart gateway reloads the running bot from the volume. No image rebuild. /status shows the model, MCPs, and version.

    Terminal showing the saved setup and Save and restart gateway.
    Saved on the volume. The gateway restarts from it.
    Screenshot: setup done

What a conversation looks like

Both images are mockups. Names and numbers in them are fictitious.

WhatsApp

Mockup of a WhatsApp self-chat. The assistant's replies start with Pi:.
Mockup of a WhatsApp chat.
Mockup: WhatsApp chat
  • Replies are plain text. Headings and bold become WhatsApp *bold*.
  • Approvals are a numbered list. Reply with the number.
  • In the linked account's own chat, replies start with Pi: .

Telegram

Mockup of a Telegram chat with the assistant.
Mockup of a Telegram chat.
Mockup: Telegram chat
  • The command menu is registered on start.
  • Approvals come with buttons.
  • Each forum topic keeps its own history, model, and effort.

What it does today

Gateway
Telegram via the Bot API, or WhatsApp linked as a device. One per install, with an allow list.
Model
Any official pi-ai provider, or ChatGPT Plus/Pro. Switch with /model and /thinking.
Photos and voice
A vision model reads photos. An audio model transcribes voice notes. Replies stay text.
Schedules
Ask for a one-off reminder or a five-field cron, each with its own timezone. A run stays silent unless it has something to say. /crons manages them.
Tools
Composio, Executor, Upsy (OAuth, no API key), a self-hosted gateway, or a JSON list of extra MCP servers.
Approvals
When Executor pauses a call, the bot relays it. A write whose result is unknown is not resent. /resume continues or dismisses it.
Conversations
/new starts fresh and keeps the old one on the volume. /compact condenses a long thread. On Telegram, each forum topic is separate.
Skills
SKILL.md folders on the volume, named in config.yaml. The model can read them on every reply, including scheduled runs.
Code tasks
sandbox_code_task runs a long coding job on an Instabox machine. Off until you configure it. The repository allow list starts empty. Pushes and pull requests wait for approval.
Host
Docker Compose, a read-only image, capabilities dropped, and a health check. Configured secrets are redacted from logs.

Commands

On Telegram these appear in the bot menu. On WhatsApp, type them. Names stay in English.

Command What it does
/status Model, tokens and cost, MCPs, and version
/model Choose the provider and model
/thinking Choose the reasoning effort
/crons List schedules. On WhatsApp, reply with a number to turn one on or off
/new Start a new conversation. The old one stays on the volume
/compact Condense this conversation. Text after the command is optional focus
/resume Resume a stuck task, or dismiss an uncertain result
/stop Stop the current work
/help Show this list

Questions

Can one install use Telegram and WhatsApp together?

No. Each install has one gateway. Saving WhatsApp turns Telegram off, and the other way around. An install that never chooses stays on Telegram.

Is the WhatsApp connection official?

No. The gateway uses Baileys, which speaks the unofficial WhatsApp Web protocol and can lead to account restrictions.

Do I need an API key?

Not for ChatGPT Plus/Pro sign-in. Every other official pi-ai provider asks for its key in setup.

Where is the data stored?

On the Docker volume pi_bot_data, mounted at /app/data: settings, credentials, conversations, and the WhatsApp session. The image is read-only.

Can it answer with voice?

No. It transcribes voice notes when an audio model is set, and it always replies in text. A tool can produce an audio file. A voice bubble is not implemented.

Is it ready for production?

Pi Bot is in beta: usable day to day, but configuration and commands can still change. Back up the volume before upgrading.