A lightweight, memory-efficient AI-powered Telegram bot designed for Raspberry Pi Zero 2W
Features • Quick Start • Hardware • Installation • Usage • API
- Overview
- Performance
- Features
- Quick Start
- Hardware Requirements
- Installation
- Configuration
- Usage
- LCD Display Setup
- Running as a Service
- Architecture
- Troubleshooting
- Contributing
- License
Moltbot Pi is a production-ready, lightweight implementation of an AI-powered Telegram bot specifically optimized for resource-constrained devices. Built with a modular architecture and lazy-loading system, it delivers full AI capabilities while consuming minimal system resources.
| Challenge | Solution |
|---|---|
| Limited RAM (512MB) | Lazy-loading architecture, only loads modules when needed |
| Slow storage (SD Card) | Minimal dependencies (34MB vs 700MB) |
| Limited CPU | Efficient async operations, no heavy processing |
| Power constraints | Low idle consumption (~85MB RAM) |
|
|
|
|
# Clone the repository
git clone https://github.com/Pavelevich/moltbot-pi.git
cd moltbot-pi
# Install dependencies
npm install --omit=optional
# Configure environment
cp .env.example .env
nano .env # Add your API keys
# Run the bot
node --experimental-strip-types src/bot.ts| Component | Specification | Notes |
|---|---|---|
| Board | Raspberry Pi Zero 2W | Quad-core ARM Cortex-A53, 512MB RAM |
| Storage | MicroSD 8GB+ | Class 10 / U1 recommended |
| Power | 5V 2.5A USB | Stable power supply required |
| Network | WiFi 802.11 b/g/n | Built-in on Pi Zero 2W |
|
Waveshare 1.44" LCD HAT
|
GPIO Pinout |
┌─────────────────────────────────────────┐
│ Waveshare 1.44" HAT │
├─────────────────────────────────────────┤
│ KEY1 ─── GPIO 21 JOY UP ─── GPIO 6 │
│ KEY2 ─── GPIO 20 JOY DN ─── GPIO 19 │
│ KEY3 ─── GPIO 16 JOY LT ─── GPIO 5 │
│ JOY RT ─── GPIO 26 │
│ JOY OK ─── GPIO 13 │
└─────────────────────────────────────────┘
- Raspberry Pi OS (64-bit Lite recommended)
- Node.js 22 or higher
- Internet connection
# Update system
sudo apt update && sudo apt upgrade -y
# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Verify installation
node --version # Expected: v22.x.x# Clone repository
git clone https://github.com/Pavelevich/moltbot-pi.git
cd moltbot-pi
# Install dependencies (lightweight)
npm install --omit=optional --ignore-scripts
# Verify installation
ls node_modules | wc -l # Expected: ~100 packages
du -sh node_modules # Expected: ~34MB# Create environment file
cp .env.example .env
# Edit configuration
nano .envCreate a .env file in the project root:
# ═══════════════════════════════════════════════════════════
# MOLTBOT PI - CONFIGURATION
# ═══════════════════════════════════════════════════════════
# Telegram Bot Token (Required)
# Get from: https://t.me/BotFather
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# DeepSeek API Key (Required)
# Get from: https://platform.deepseek.com
DEEPSEEK_API_KEY=your_deepseek_api_key
# Telegram Admin ID (Optional)
# Your Telegram user ID for admin commands
# Get your ID by sending /whoami to the bot
TELEGRAM_ADMIN_ID=your_telegram_user_id
# Vault Password (Optional)
# Password for encrypting stored files
VAULT_PASSWORD=your_secret_password
# Tapo Smart Home (Optional)
# TP-Link Tapo account for /home commands
TAPO_EMAIL=your_tapo_email@example.com
TAPO_PASSWORD=your_tapo_password
# Profile (Optional - defaults to raspberry-pi)
MOLTBOT_PROFILE=raspberry-pi📱 Telegram Bot Token
- Open Telegram and search for @BotFather
- Send
/newbotcommand - Choose a display name (e.g., "My Pi Assistant")
- Choose a username ending in
bot(e.g., "my_pi_assistant_bot") - Copy the token provided (format:
123456789:ABCdefGHI...)
🤖 DeepSeek API Key
- Visit platform.deepseek.com
- Create an account or sign in
- Navigate to API Keys section
- Click Create new API key
- Copy the key (format:
sk-...)
Pricing: ~$0.14 per 1M tokens (very affordable)
# Development mode
node --experimental-strip-types src/bot.ts
# With environment variables
source .env && node --experimental-strip-types src/bot.ts
# Background process
nohup node --experimental-strip-types src/bot.ts > bot.log 2>&1 &
# View logs
tail -f bot.log| Command | Description |
|---|---|
/start |
Welcome message & command list |
/help |
Show all available commands |
/status |
System status (RAM, CPU temp, uptime) |
/temp |
CPU temperature |
/disk |
Disk space usage |
/network |
Network info (IP, hostname, WiFi) |
/uptime |
System uptime |
/whoami |
Get your Telegram user ID |
[any text] |
Chat with DeepSeek AI |
| Command | Description |
|---|---|
/vault |
List stored files |
/vault get <name> |
Retrieve a file |
/vault delete <name> |
Delete a file |
[send any file] |
Store file in encrypted vault |
| Command | Description |
|---|---|
/remind in 30 minutes <msg> |
Remind in X minutes |
/remind at 14:00 <msg> |
Remind at specific time |
/remind tomorrow at 9:00 <msg> |
Remind tomorrow |
/reminders |
List active reminders |
/remind cancel <id> |
Cancel a reminder |
| Command | Description |
|---|---|
/home |
Status of all devices |
/home devices |
List all devices |
/home on <device> |
Turn device on |
/home off <device> |
Turn device off |
/home toggle <device> |
Toggle device |
/home temp |
Temperature sensors |
/home sensors |
All sensor readings |
| Command | Description |
|---|---|
/bash <cmd> |
Run shell command on the Pi |
/read <path> |
Read file contents |
/write <path> <text> |
Write text to file |
/gpio <pin> <on|off|read> |
Control GPIO pins |
/reboot |
Reboot the Raspberry Pi |
/shutdown |
Shutdown the Raspberry Pi |
| Command | Description |
|---|---|
/security |
Overview of all security commands |
/scan |
Scan network for connected devices |
/scan ports <ip> |
Port scan a specific IP |
/alerts |
Check for unknown/suspicious devices |
/honeypot |
Intrusion detection honeypot status |
/honeypot start <ssh|ftp|http|telnet> |
Start a honeypot service |
/honeypot logs |
View intrusion attempts |
/wifi |
WiFi security audit |
/wifi scan |
Scan nearby WiFi networks |
/breach email <email> |
Check email in breach databases |
/breach password <pass> |
Check if password was leaked |
/2fa add <name> <secret> |
Add TOTP 2FA secret |
/2fa get <name> |
Get current 2FA code |
/2fa list |
List all 2FA services |
/dns |
Pi-hole DNS status |
/dns enable |
Enable ad blocking |
/dns disable |
Disable ad blocking |
/vpn |
WireGuard VPN status |
/vpn up |
Connect to VPN |
/vpn down |
Disconnect from VPN |
Instead of using specific commands, you can just ask the AI in plain English:
| Natural Language | What It Does |
|---|---|
| "Scan my network" | Runs network scanner |
| "Is password123 safe?" | Checks breach database |
| "Turn on the lights" | Controls Tapo devices |
| "Start the honeypot" | Starts intrusion detection |
| "Show security alerts" | Displays honeypot logs |
| "Get my GitHub 2FA code" | Generates TOTP code |
| "How's the Pi doing?" | Shows system status |
| "Check ports on 192.168.1.1" | Runs port scan |
The AI understands context and can execute tools automatically when you ask naturally.
You: /start
Bot: 🤖 Moltbot Pi - Raspberry Pi AI Bot
Send me any message to chat with AI.
You: /status
Bot: 📊 Moltbot Pi Status
🖥️ Raspberry Pi Zero 2W
⏱️ Uptime: 2h 15m
💾 RAM: 87 MB
🌡️ CPU: 45.2°C
📁 Vault: 3 files
⏰ Reminders: 2 active
🏠 Tapo: Connected
You: /remind in 30 minutes check laundry
Bot: ✅ Reminder set for 3:45 PM
"check laundry"
You: /home on living_room
Bot: 💡 OK: living_room turned ON
You: /home temp
Bot: 🌡️ Temperature
bedroom_sensor: 22.5°C, 45% humidity
kitchen_sensor: 24.1°C, 38% humidity
You: [sends a PDF file]
Bot: ✅ Stored "document.pdf" in vault
Retrieve with: /vault get document.pdf
You: Explain Docker in simple terms
Bot: Docker is like a shipping container for software...
- Start the bot and send
/whoami - Copy your Telegram user ID from the response
- Add it to your
.envfile:TELEGRAM_ADMIN_ID=123456789 - Restart the bot
# System packages
sudo apt-get install -y python3-pip python3-pil python3-numpy
# Python libraries
pip3 install st7735 spidev RPi.GPIO gpiodevice --break-system-packages
# Enable SPI interface
sudo raspi-config
# → Interface Options → SPI → Enable# Show custom image (128x128 recommended)
python3 scripts/display_icon.py assets/Raspclaut.png
# Show text
python3 scripts/display_icon.py "ONLINE"
# Default display (MOLTBOT logo)
python3 scripts/display_icon.pyAdd to /etc/rc.local (before exit 0):
python3 /home/pi/moltbot-pi/scripts/display_icon.py /home/pi/moltbot-pi/assets/Raspclaut.png &sudo nano /etc/systemd/system/moltbot.service[Unit]
Description=Moltbot Pi - AI Telegram Bot
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/moltbot-pi
EnvironmentFile=/home/pi/moltbot-pi/.env
ExecStart=/usr/bin/node --experimental-strip-types src/bot.ts
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target# Reload systemd
sudo systemctl daemon-reload
# Enable auto-start
sudo systemctl enable moltbot
# Start service
sudo systemctl start moltbot
# Check status
sudo systemctl status moltbot
# View logs
journalctl -u moltbot -f
# Restart
sudo systemctl restart moltbot
# Stop
sudo systemctl stop moltbotmoltbot-pi/
├── src/
│ ├── bot.ts # Main entry point
│ ├── infra/
│ │ └── features.ts # Feature flags system
│ └── compat/
│ ├── index.ts # Compatibility layer
│ ├── lazy-playwright.ts # Browser (disabled)
│ ├── lazy-sharp.ts # Images (disabled)
│ ├── lazy-baileys.ts # WhatsApp (disabled)
│ ├── lazy-pdfjs.ts # PDF (disabled)
│ └── lazy-llama.ts # Local LLM (disabled)
├── scripts/
│ ├── display_icon.py # LCD display control
│ ├── tapo_cli.py # Tapo smart home CLI
│ ├── security_tools.py # Security toolkit (scanner, honeypot, etc.)
│ ├── install-raspberry-pi.sh
│ └── build-raspberry-pi.sh
├── config/
│ └── raspberry-pi.yml # Default configuration
├── assets/
│ └── Raspclaut.png # Project logo
├── .env.example # Environment template
├── .gitignore
├── package.json
├── LICENSE
└── README.md
// Profiles available:
// - 'default' → Full features (2GB+ RAM)
// - 'raspberry-pi' → Minimal (512MB RAM)
// - 'embedded' → Ultra-minimal (256MB RAM)
const features = loadFeatures(); // Auto-detects based on RAMBot won't start
# Check Node.js version (must be 22+)
node --version
# Verify environment variables
cat .env
# Check for port conflicts
lsof -i :18789
# Run with verbose output
DEBUG=* node --experimental-strip-types src/bot.tsOut of memory errors
# Check current memory
free -m
# Disable unnecessary services
sudo systemctl disable bluetooth
sudo systemctl disable avahi-daemon
# Increase swap (temporary)
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile # Set CONF_SWAPSIZE=1024
sudo dphys-swapfile setup
sudo dphys-swapfile swaponLCD display not working
# Check SPI is enabled
ls /dev/spi* # Should show spidev0.0
# Test Python imports
python3 -c "import st7735; print('ST7735 OK')"
python3 -c "import RPi.GPIO; print('GPIO OK')"
# Check wiring and connections
# Ensure HAT is properly seated on GPIO headerNetwork/WiFi issues
# Check WiFi status
iwconfig wlan0
# Restart networking
sudo systemctl restart networking
# View network logs
journalctl -u networking -fContributions are welcome! Please read our contributing guidelines before submitting a PR.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
# Clone your fork
git clone https://github.com/YOUR_USERNAME/moltbot-pi.git
# Install all dependencies (including dev)
npm install
# Run in development
npm run devThis project is licensed under the MIT License - see the LICENSE file for details.
- Moltbot - Original project inspiration
- DeepSeek - Affordable AI API
- Grammy - Excellent Telegram Bot Framework
- Waveshare - Quality LCD hardware
Built with ❤️ for the Raspberry Pi community
Created by Pavelevich