wrongname/mautrix-perplexity repository overview

⁠mautrix-perplexity

A Matrix⁠ bridge for Perplexity AI⁠ built on the mautrix bridgev2⁠ framework.

Chat with Perplexity AI models directly from any Matrix client, with built-in web search, conversation history, and multi-user support.

⁠Features

• Multiple AI models — sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro
• Web search integration — domain filtering, recency filtering, date ranges, academic mode, location-aware results, image search
• Conversation mode — optional multi-turn conversations with persistent history across restarts
• Per-room configuration — model, system prompt, temperature, web search settings, mention-only mode
• Multi-user relay — per-user session isolation in shared rooms
• Image understanding — send images to vision-capable models
• E2E encryption — optional end-to-bridge encryption support (MSC2409/MSC3202)
• Streaming responses — real-time message streaming with typing indicators
• Metrics — Prometheus endpoint with request counts, latency histograms, token usage, active sessions

⁠Architecture

The container runs two processes:

The Python sidecar is required because the official Perplexity SDK is Python-only. Both processes start automatically via the container entrypoint.

Matrix Client → Homeserver → Go Bridge (port 29321) → Python Sidecar (port 8090) → Perplexity API

Each Perplexity model appears as a separate ghost user in Matrix (e.g. @perplexity_sonar:yourdomain.com).

⁠Quick Start

⁠1. Generate config

docker run --rm -v ./data:/data wrongname/mautrix-perplexity

Edit data/config.yaml — set homeserver.address, homeserver.domain, and bridge.permissions.

⁠2. Generate registration

docker run --rm -v ./data:/data wrongname/mautrix-perplexity

Register the generated data/registration.yaml with your homeserver:

• Synapse: Add the file path to app_service_config_files in homeserver.yaml
• Dendrite: Add the file path to app_service_api.config_files in dendrite.yaml

⁠3. Run

docker run -d --restart unless-stopped \
  -v ./data:/data \
  wrongname/mautrix-perplexity

Or with Docker Compose:

services:
  mautrix-perplexity:
    image: wrongname/mautrix-perplexity:latest
    restart: unless-stopped
    volumes:
      - ./data:/data
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:29321/_matrix/mau/ready"]
      interval: 30s
      timeout: 10s
      retries: 3

⁠4. Log in

1. Start a direct chat with the bridge bot (e.g. @perplexitybot:yourdomain.com)
2. Send !perplexity login
3. Enter your Perplexity API key (from perplexity.ai/settings/api⁠)

⁠5. Start a conversation

Invite the bot to a room and send:

!perplexity join

Perplexity AI will now respond to messages in that room.

⁠Commands

All commands use the !perplexity prefix (configurable).

⁠Web search options

!perplexity web domains docs.python.org,stackoverflow.com
!perplexity web recency week
!perplexity web after 01/01/2025
!perplexity web before 06/01/2025
!perplexity web mode academic
!perplexity web location Berlin,Berlin,Germany
!perplexity web images on
!perplexity web context high

⁠Configuration

Key options in config.yaml under the network section:

Bridge permissions:

bridge:
  permissions:
    "*": relay
    "example.com": user
    "@admin:example.com": admin

⁠Supported Databases

• SQLite (default) — no additional setup needed
• PostgreSQL — for larger deployments; set appservice.database to a postgres:// URI

⁠Sidecar Environment Variables

⁠Health Checks

⁠Volumes

⁠Ports

⁠Runtime Details

• Base image: Debian Bookworm (slim)
• Runs as: unprivileged bridge user (UID 1337)
• Default port: 29321
• Memory: 256 MB typical, 1 GB recommended limit

⁠Source

https://dev.web.wr0ng.name/wrongname/mautrix-perplexity⁠