Prism Icon # Prism **Self-hosted notification gateway with email monitoring** [Setup](#setup) • [Integrations](#integrations) • [API](#api) • [Examples](#real-world-examples) • [Monitoring](#monitoring)
Prism is a self-hosted notification gateway. Prism can receive messages and route them to Signal, Telegram or WebPush URLs. Messages can be sent via webhooks or monitored from a Proton Mail account integration. Prism also comes with an Android companion app: [prism-android](https://github.com/lone-cloud/prism-android) ## Setup ### Docker (Recommended) ```bash # Create .env file curl -L -O https://raw.githubusercontent.com/lone-cloud/prism/master/.env.example mv .env.example .env nano .env # Set API_KEY=your-secret-key-here # Run Prism docker run -d \ --name prism \ -p 8080:8080 \ -v prism-data:/app/data \ -v signal-data:/home/prism/.local/share/signal-cli \ --env-file .env \ ghcr.io/lone-cloud/prism:latest ``` ### Binary (Alternative) ```bash # Download latest release curl -L -O https://github.com/lone-cloud/prism/releases/latest/download/prism-linux-amd64 chmod +x prism-linux-amd64 mv prism-linux-amd64 prism # Create .env file curl -L -O https://raw.githubusercontent.com/lone-cloud/prism/master/.env.example mv .env.example .env nano .env # Set API_KEY=your-secret-key-here # Run Prism ./prism ``` Prism is now running at . ![Prism Dashboard](assets/screenshots/dashboard.webp) ## Integrations All integrations are configured through the web UI - no environment variables or command-line setup needed! Authenticate using your `API_KEY` as the password (username can be anything). ### Signal Send notifications through Signal Messenger. **Setup:** 1. Visit and authenticate with your API_KEY 2. Expand the Signal integration card 3. Click "Link Device" 4. Scan the QR code with Signal on your phone: - Open Signal → Settings → Linked Devices → Link New Device - Scan the displayed QR code 5. Your device will link automatically All notifications will be sent via Signal. **Note:** If running the binary directly (not Docker), you'll need [signal-cli](https://github.com/AsamK/signal-cli/releases) installed and in your PATH. Docker images include signal-cli automatically. ### Telegram Send notifications through a Telegram bot. **Setup:** 1. Create a bot: - Message [@BotFather](https://t.me/BotFather) on Telegram - Send `/newbot` and follow the prompts - Copy the bot token 2. Get your Chat ID: - Message [@userinfobot](https://t.me/userinfobot) on Telegram - Copy your Chat ID from the response 3. Configure in Prism: - Visit and authenticate with your API_KEY - Expand the Telegram integration card - Enter your bot token and chat ID - Click "Configure" All notifications will be sent to your Telegram chat. ### Proton Mail Monitor a Proton Mail account and forward new emails as notifications through Signal or Telegram. **Features:** - Monitors inbox for new emails in real-time - Supports 2FA-enabled accounts - Auto-creates "Proton Mail" app for received emails - Secure credential storage with AES-256-GCM encryption - Automatic token refresh - no re-authentication needed **Setup:** 1. Visit and authenticate with your API_KEY 2. Configure Signal or Telegram first (required for routing) 3. Expand the Proton Mail integration card 4. Enter your Proton Mail credentials: - Email address - Password - 2FA code (if enabled) 5. Click "Link" Proton Mail will connect and begin monitoring. New emails will appear as notifications from the "Proton Mail" app. **Note:** Prism uses the official Proton Mail API (same as the Proton Bridge). Credentials are encrypted and stored locally. Tokens refresh automatically in the background. ### WebPush Send notifications directly to your browser. **Setup:** 1. Visit and authenticate with your API_KEY 2. Allow browser notifications when prompted 3. Apps without Signal or Telegram configured will automatically use WebPush You'll receive browser notifications when messages arrive. ## API All API endpoints require authentication with your API key: ```bash Authorization: Bearer YOUR_API_KEY ``` ### ntfy-compatible publish API Publish notifications to `POST /{appName}`. `{appName}` is the target app/topic name. Messages are routed to all subscriptions configured for that app (Signal, Telegram, WebPush). **JSON payload:** ```bash curl -X POST http://localhost:8080/my-app \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title": "Alert", "message": "Something happened"}' ``` **Plain text payload:** ```bash curl -X POST http://localhost:8080/my-app \ -H "Authorization: Bearer YOUR_API_KEY" \ -d "Simple message text" ``` ### WebPush subscription API Register and remove WebPush subscriptions for an app. #### POST /api/v1/webpush/subscriptions Creates a WebPush subscription. Required fields: - `appName` - `pushEndpoint` Optional encrypted payload fields (must be provided together): - `p256dh` - `auth` - `vapidPrivateKey` ```bash curl -X POST http://localhost:8080/api/v1/webpush/subscriptions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "appName": "my-app", "pushEndpoint": "https://example.push.service/send/abc123", "p256dh": "BASE64URL_P256DH", "auth": "BASE64URL_AUTH", "vapidPrivateKey": "BASE64URL_VAPID_PRIVATE_KEY" }' ``` Minimal registration (without encrypted payload fields): ```bash curl -X POST http://localhost:8080/api/v1/webpush/subscriptions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "appName": "my-app", "pushEndpoint": "http://localhost:9001/mock-push" }' ``` #### DELETE /api/v1/webpush/subscriptions/{subscriptionId} Removes a WebPush subscription by ID. ```bash curl -X DELETE http://localhost:8080/api/v1/webpush/subscriptions/SUBSCRIPTION_ID \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Real-World Examples ### Email Monitoring Receive instant Signal, Telegram or WebPush notifications when new emails arrive in your Proton Mail inbox. Prism monitors your Proton Mail account using the official Proton API and forwards new emails as notifications. Perfect for monitoring important accounts without constantly checking email. ### Home Assistant Alerts Add a rest notification configuration (eg. add to configuration.yaml) to Home Assistant like: ```yaml notify: - platform: rest name: Prism resource: "http:///Home Assistant" method: POST_JSON title_param_name: title headers: Authorization: !secret prism_api_key ``` Since Home Assistant and Prism are both on your local network, HTTP is allowed automatically - no additional configuration needed. Add your API_KEY to your secrets.yaml: ```bash prism_api_key: "Bearer YOUR_API_KEY_HERE" ``` Reboot your Home Assistant system and you'll then be able to send Signal notifications to yourself by using this notify prism action. ### Beszel Alerts [Beszel](https://beszel.dev) is a lightweight server monitoring tool. You can forward its alerts through Prism using the ntfy-compatible URL format. In Beszel's **Settings → Notifications**, add a URL: ``` ntfy://:YOUR_API_KEY@:/Beszel?disableTLS=yes ``` - Replace `YOUR_API_KEY` with your Prism API key - Replace `:` with your Prism server address (e.g. `192.168.0.10:8080`) - `disableTLS=yes` is only required for local HTTP deployments - `Beszel` is the app name that will appear in Prism — change it to anything you like ## Monitoring ### Health Endpoints #### GET /health Public health check endpoint (no authentication required). Returns `200 OK` when the service is running. Used for Docker health checks and load balancer health probes. ```bash curl http://localhost:8080/health ``` #### GET /api/v1/health Detailed health endpoint (requires authentication). Returns JSON with uptime and integration status: ```bash curl http://localhost:8080/api/v1/health \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```json { "version": "0.2.0", "uptime": "2h15m", "signal": {"linked": true, "account": "+1234567890"}, "telegram": {"linked": true, "account": "123456789"}, "proton": {"linked": true, "account": "user@proton.me"} } ``` ## API Key Security Your API_KEY is both the login password and the master encryption key for all integration credentials. Use a strong unique password. Changing it will make all encrypted credentials unrecoverable.