Skip to content
mattv8Public

About

Self-hosted encrypted device messaging with desktop and native mobile clients

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1,296 Commits

Folders and files

Repository files navigation

Peppy

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.

CI License: Apache-2.0

Get the apps · Peppy Hosted · Self-host · Contributing

peppy-promo.mp4

What you can do

  • 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.

How it works

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
Loading

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.

Get the apps

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.

Full guide →

Connect your phone

  1. Set up Peppy in the browser or desktop app.
  2. 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.
  3. Scan the code with Peppy on your phone.
  4. 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.

Full guide →

Peppy Hosted

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.

Full guide →

Self-host

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.

  1. Create your environment file.

    cp .env.example .env

    In .env:

    • Set PUBLIC_HOST to your hostname.
    • Set POSTGRES_PASSWORD, PEPPY_RUNTIME_DB_PASSWORD, PEPPY_MAINTENANCE_DB_PASSWORD, and S3_SECRET_KEY to long random values. The three database passwords can contain only letters, digits, and . _ ~ -.
    • Set PEPPY_SETUP_TOKEN if you want setup to require a code. See First-run setup.

    These are the five required values. PUBLIC_API_URL defaults to https://PUBLIC_HOST, and PEPPY_ENV defaults to production. The database names and users, database-role names, and S3_ACCESS_KEY use their defaults; change them only before the first start. Compose uses the current stable :latest server image by default. You may pin PEPPY_SERVER_IMAGE or PEPPY_MCP_IMAGE to a version tag or digest instead.

  2. Start the server.

    docker compose up -d

    It listens on http://127.0.0.1:7000 and serves the browser client at that address.

  3. 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_CIDRS to that proxy's addresses only.

  4. 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.

Full guide →

First-run setup

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.

Full guide →

Recover from an unwanted first claim

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:

  1. 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"
  2. Stop that deployment and remove its containers, but not its volumes.

  3. Remove only that project's postgres-data, seaweed-volume-data, and seaweed-filer-data volumes.

  4. Set PEPPY_SETUP_TOKEN in .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.

Full guide →

Update

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 -d

Leaving 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.

Full guide →

What Peppy protects, and what it does not

  • 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.

Full guide →

Status

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.

Contributing

Read CONTRIBUTING.md for development workflows, checks, and supported toolchains.

License

Peppy is licensed under Apache-2.0, as declared in the workspace manifest.

About

Self-hosted encrypted device messaging with desktop and native mobile clients

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages