Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chamilonster/Piumy/llms.txt

Use this file to discover all available pages before exploring further.

Piumy is a self-hosted WhatsApp switchboard that runs on a Raspberry Pi Zero 2 W (or any ARM64 board, or your PC). The board routes and stores — it never thinks and never initiates. Your AI agent connects over MCP from a separate machine with RAM, reads the queue, and sends replies through the governor’s anti-ban pacing. A pwnagotchi-style e-paper face reacts to every event in real time.

Quickstart

Run the core and render the e-paper face on your PC in minutes — no hardware, no WhatsApp required.

Architecture

Understand how the switchboard, MCP server, adapters, and AI agent fit together.

Install on Raspberry Pi

One-command installer for Raspberry Pi OS Lite 64-bit with systemd services.

MCP Tools Reference

Full reference for all 19 MCP tools your AI agent uses to read chats and send replies.

​
How it works

WhatsApp (dedicated number)
      │
      ▼
  SWITCHBOARD (Go, tiny board) ── e-paper (Python adapter) → face
   · receives / stores (SQLite)     └ reads status.json
   · per-chat mode: auto | advanced
   · anti-ban governor · whitelist
   · exposes MCP ──────────────┐
        │ auto                 │ advanced (queue, pull)
        ▼                      ▼
   cheap API             AGENT over MCP (your PC)
   (optional)             Claude / OpenCode + tools
The switchboard does not reply — it routes and stores. Replies come from whoever connects over MCP. The seams are data contracts: status.json (core ↔ display) and MCP/HTTP (core ↔ agent).

​
Get started in three steps

1

Try it on your PC — no hardware needed

Run the Go core to write a status.json, then render the e-paper face as a PNG. Zero WhatsApp, zero hardware required.
cd core && go run . state responding
cd ../adapters/display/file
pip install -r requirements.txt
python render.py   # → display.png
2

Deploy to a Raspberry Pi

Flash Raspberry Pi OS Lite 64-bit, clone the repo, and run the one-command installer. It provisions systemd services and applies power-loss resilience measures.
sudo ./deploy/install.sh
See Install on Raspberry Pi for full details.
3

Connect your AI agent

Generate an MCP bearer token, paste it into your Claude Code or OpenCode .mcp.json, and point your agent at the switchboard.
sudo /opt/pimywa/pimywa auth setup
See MCP Authentication for the exact client config snippet.

​
Key features

WhatsApp Gateway

Receives, stores, and routes messages via whatsmeow. All history lives in a local SQLite database — it’s yours.

MCP Interface

19 tools for your AI agent: read chats, pull the queue, send replies, manage memory and context per contact.

Anti-Ban Governor

Rate limits, randomized human-pacing delays, a mute/kill switch, and reconnect backoff protect your account.

E-Paper Face

Real pwnagotchi kaomoji faces with a 12-frame eye-gaze loop, animated reactions to every event.

Web Dashboard

Battery chart, WhatsApp link/QR, per-chat rules, rate limits, and router config — served on LAN port 80.

Session Backup

Encrypted session snapshots with scrypt key derivation. Restore from backup with a single CLI command.

​
License

Piumy is AGPL-3.0. You are free to use, modify, and distribute it — your version must also be AGPL-3.0. A commercial license is available for closed-source products.

Build docs developers (and LLMs) love

Get started for freeTalk to us