Private messaging on a server you control.
Read and answer your phone's texts from a browser or desktop app.
Your devices encrypt what they sync, on Peppy Hosted or on your own server.
peppy-promo.mp4
- Text from your computer. Send and receive SMS through your Android phone from the browser or desktop app. MMS, for pictures and group texts, is opt-in and experimental.
- Keep your RCS chats. Link Google Messages on your phone to send and receive RCS text in the one-to-one chats and groups it already has.
- Use your phone's contacts. Browse them on the desktop and request edits. The phone that owns a contact applies the change under its own contact-sync setting.
- See phone notifications on your desktop. Android notification mirroring is opt-in, and you choose which apps it includes.
- Keep conversations close. On macOS and Windows, the desktop app sits in the menu bar or system tray and shows your unread count. You can pin up to eight floating conversations.
- Connect AI clients and automations. On a server that runs the optional MCP worker, you can give each AI client its own read and send permissions and add signed webhooks for incoming SMS and MMS.
- Share a server. On a self-hosted server, the administrator can invite other people to create their own separate vaults.
flowchart LR
subgraph Vault[Encrypted by your devices]
direction LR
Computer[Browser or desktop app]
Phone[Android phone]
Server[(Peppy server)]
end
Computer <--> Server
Phone <--> Server
Phone <--> Carrier[Carrier SMS, MMS, RCS]
style Carrier stroke-dasharray: 5 5
Your phone still sends and receives every text. Peppy on Android runs beside your usual messaging app, copies messages into an encrypted vault, and sends what you write on your other devices.
The server stores that vault and passes it between your devices. It never receives your Vault key phrase.
The dashed box is your carrier's network. Peppy's encryption does not reach it, so a text sent through Peppy is as private as any other SMS, MMS, or RCS message.
| Device | What it does | How to get it |
|---|---|---|
| Browser | Full messaging in a desktop browser. | Open your server's HTTPS address. |
| macOS, Windows, Linux | Desktop app with notifications and floating conversations. | GitHub Releases |
| Android | Companion app that connects your phone's texts, contacts, and notifications. | The APK in the latest android-v* release |
| iPhone and iPad | Sync, contacts, and device management. It cannot send or receive carrier texts. | No installable build yet. |
Android releases are numbered separately from desktop releases.
- Set up Peppy in the browser or desktop app.
- Select the Connect a phone icon in the title bar. Peppy shows a QR code. The icon appears for the vault owner, and only while no phone is connected.
- Scan the code with Peppy on your phone.
- Check that both devices show the same verification code, then approve.
On a self-hosted server, you can also join from any device by entering the server address and your Vault key phrase.
On Android, texting needs SMS permission and mirroring needs notification access. Peppy does not ask to become your default messaging app.
Peppy Hosted is the managed service: the same apps, with the server run for you. Sign in at peppy.pro to create an account, subscribe, and download the apps.
The Community server runs with Docker Compose. You need:
- Docker Engine with Docker Compose v2.24 or newer.
- For access from other devices, a hostname that resolves to the server, with ports 80 and 443 open.
The Compose file needs only a .env beside it.
-
Create your environment file.
cp .env.example .env
In
.env:- Set
PUBLIC_HOSTto your hostname. - Set
POSTGRES_PASSWORD,PEPPY_RUNTIME_DB_PASSWORD,PEPPY_MAINTENANCE_DB_PASSWORD, andS3_SECRET_KEYto long random values. The three database passwords can contain only letters, digits, and._~-. - Set
PEPPY_SETUP_TOKENif you want setup to require a code. See First-run setup.
These are the five required values.
PUBLIC_API_URLdefaults tohttps://PUBLIC_HOST, andPEPPY_ENVdefaults toproduction. The database names and users, database-role names, andS3_ACCESS_KEYuse their defaults; change them only before the first start. Compose uses the current stable:latestserver image by default. You may pinPEPPY_SERVER_IMAGEorPEPPY_MCP_IMAGEto a version tag or digest instead. - Set
-
Start the server.
docker compose up -d
It listens on
http://127.0.0.1:7000and serves the browser client at that address. -
Add HTTPS so other devices can connect. Add the Caddy overlay.
docker compose -f docker-compose.yml -f infra/compose/compose.caddy.yml up -d
Caddy publishes ports 80 and 443. If you use another reverse proxy, set
TRUSTED_PROXY_CIDRSto that proxy's addresses only. -
Open the address in a browser, or enter it in a desktop or mobile app, and finish setup.
To check a running server, request /healthz for the process and /readyz for the database, migrations, and attachment storage.
To build from source instead, see CONTRIBUTING.md.
The first device to finish setup becomes the administrator and creates the first vault.
A new server is open by default: anyone who can reach it can claim it during the 60 minutes after it starts. After that, restart the server to continue setup. To require a setup code instead, set PEPPY_SETUP_TOKEN to a random value of at least 32 bytes before you start the server.
Setup involves three separate secrets:
| Secret | What it is for |
|---|---|
| Setup code | Claims a token-protected server. It is the value of PEPPY_SETUP_TOKEN. |
| Administrator password | Signs you in to manage the server. |
| Vault key phrase | Protects your messages and admits new devices. Peppy generates it. |
Save the Vault key phrase when Peppy shows it. The server never has it, so neither the server nor its logs can give it back.
If someone else claims your server first, Peppy cannot reset their password or hand the server back. You have to erase the server and set it up again:
-
List the volumes of the affected Compose project and confirm their names. Compose prefixes each with the project name.
docker volume ls --filter "label=com.docker.compose.project=$PROJECT" -
Stop that deployment and remove its containers, but not its volumes.
-
Remove only that project's
postgres-data,seaweed-volume-data, andseaweed-filer-datavolumes. -
Set
PEPPY_SETUP_TOKENin.env, start the deployment with the same project name, Compose files, and.env, then complete setup straight away.
This permanently destroys every vault and attachment on that server. Do not run docker compose down -v, and never remove another project's volumes. A development stack from the same checkout uses the same volume names, so check the project before you delete. If your database or attachment storage is external, clear only Peppy's own database and attachment data there instead.
Read the backup and restore guide before you remove anything.
Back up first. If .env sets PEPPY_SERVER_IMAGE or PEPPY_MCP_IMAGE, change
them to the release you want, or delete them to follow :latest; a pinned image
does not change on pull. Then pull and recreate with the same Compose files you
started with, for example with the HTTPS and MCP overlays:
docker compose -f docker-compose.yml -f infra/compose/compose.caddy.yml -f infra/compose/compose.mcp.yml pull
docker compose -f docker-compose.yml -f infra/compose/compose.caddy.yml -f infra/compose/compose.mcp.yml up -dLeaving out an overlay you use recreates api without it; dropping the MCP
overlay disconnects the worker. The :latest tag moves with each stable
release. Migrations cannot be rolled back, so keep the backup until you confirm
the update. The backup and restore guide
and the release update guide have the details.
Peppy runs on a single node. It is not a high-availability deployment.
- Your devices encrypt messages, attachments, and contacts before they sync. The server stores the encrypted data and never receives your Vault key phrase.
- SMS, MMS, and RCS travel through your carrier or Google Messages, outside Peppy's encryption.
- Everyone who knows the Vault key phrase can read the vault. Removing a device does not take the phrase away from someone who knows it. Rotating the phrase protects new messages only: anyone who had the old phrase can still read earlier history.
- A public image link publishes a separate, unencrypted copy of that image. The link has its own expiry and can be revoked.
- Turning on MCP lets the server hold keys for that vault. Webhooks send message text to the address you choose.
- Peppy does not claim forward secrecy, and it has not had an external security audit.
Peppy is in active development. MMS is experimental, pictures and files over RCS are still in progress, and carrier behavior varies by phone and network.
Read CONTRIBUTING.md for development workflows, checks, and supported toolchains.
Peppy is licensed under Apache-2.0, as declared in the workspace manifest.