Happier Docs
Advanced (optional)

Notifications

Push notifications (Expo + FCM/APNs) for CLI events and self-hosting.

Happier uses Expo Push Notifications as a delivery mechanism. In the current architecture:

  • The mobile app registers an Expo push token and saves it to the server.
  • The server stores push tokens per account (it does not send push payloads).
  • The CLI fetches the user’s saved tokens from the server and sends notifications via Expo’s push API (for example: “It’s ready!” or Permission Request).

What notifications can do

Happier can notify you when a session needs attention, including:

  • Ready notifications when a turn finishes and the agent is waiting
  • Permission requests when a tool/action needs approval
  • User-action requests when the agent needs a structured human response

On the mobile app, permission and action-request notifications can also expose action buttons:

  • Permission requests: Allow / Deny
  • User-action requests: Answer

Current behavior is intentionally conservative:

  • tapping the notification opens the targeted session
  • pressing a notification action button also opens the app
  • Happier only auto-sends a permission response when the notification’s server is already active or already saved on the device
  • if the server is not saved yet, Happier routes you into the safest add/switch flow instead of silently approving on the wrong server

For the exact routing behavior, see Notification routing.

Richer notification details

Permission and action-request notifications include more context than a generic “the app needs permission” alert.

In current builds, Happier tries to show:

  • the tool or request type being asked for
  • a short detail hint when it is useful and safe to show

Examples of detail hints include:

  • a short file hint such as src/file.ts
  • a command hint such as Command: npm
  • a compact question count such as 1 question or 3 questions

Happier does not try to dump full raw tool input into the push notification. The goal is to give you enough context to decide quickly without exposing unnecessary command arguments or request payloads on the lock screen.

Platform details:

  • iOS can show the tool/request name as a notification subtitle
  • Android uses dedicated channels for permission requests and action requests so users can tune them separately at the OS level

Notification preferences

The app also exposes notification preferences so users can tune how noisy Happier should be.

Current settings include:

  • Push notifications on/off for the account
  • per-type toggles for Ready, Permission requests, and User-action requests
  • In-app notifications behavior while the app is open: Full, Silent, or Off

When you are already looking at a given session, Happier suppresses notifications for that same session to avoid duplicate noise while you are actively reading it.

What you need to configure

1) Server (any deployment)

Your server must expose the push token routes:

  • POST /v1/push-tokens
  • GET /v1/push-tokens
  • DELETE /v1/push-tokens/:token

If you’re self-hosting the server, see: Deployment → Docker / Environment variables.

2) Mobile app (iOS + Android)

For self-hosting, the recommended flow is:

  1. Self-host the server, then
  2. Use the Happier app and set its Server URL to your instance.

In this setup, you do not need to configure APNs/FCM yourself. The app already includes the required push notification credentials; your server just stores the user’s Expo push tokens.

3) CLI (sender)

The CLI sends notifications by:

  1. Calling your server to fetch saved Expo push tokens for the authenticated user.
  2. Sending push payloads via Expo’s push API to those tokens.

If a user runs their own server + CLI, they must:

  • Point both app and CLI at the same server URL.
  • Ensure the server stores push tokens (routes above).

Self-hosting checklists

  1. Deploy the server.
  2. In the Happier app, set Server URL to your server.
  3. Run the CLI against that same server URL.

Once the app has registered a push token to your server, the CLI can send notifications (including permission notifications) via Expo.

Multi-server behavior

Notifications are also multi-server-aware.

When a notification targets a different server than the one currently active in the app, Happier tries to route you correctly:

  • if that server is already saved, Happier switches to it first
  • if it is the first server on the device, Happier can bootstrap that server so the deep link still works
  • if the app already has saved servers and the incoming server is not one of them, Happier opens Server settings with the URL prefilled so you can review and add it explicitly

After you add and use that server, Happier continues to the original session/request automatically.

See Multi-server and Notification routing for the full user-facing flow.

API key restrictions (Android / Firebase)

For Firebase Android configs, the API key embedded in google-services.json is client-side. Security comes from restrictions, not secrecy:

In Google Cloud Console, restrict the API key to:

  • Android apps
  • Your app’s package name(s)
  • Your signing certificate SHA-1 fingerprint(s)

Finding the SHA-1 fingerprints you should add

You typically need more than one SHA-1 during development and release:

  • Debug / dev builds (your dev keystore)
  • Release builds (your release/upload keystore)
  • Play Store installs (the Play App Signing key, once enabled)

Common places to find them:

  • EAS: view Android credentials and copy the keystore SHA-1 (upload/release key).
  • Play Console (after enabling Play App Signing): App integrity → App signing certificate → SHA-1.
  • Firebase Console: Project settings → Your apps → Android app → add SHA-1 fingerprints (so Firebase recognizes the signing cert).

Note: the “fingerprint” shown in EAS build lists is not the same thing as the Android signing certificate SHA-1.

If you use Firebase Cloud Messaging only, Google’s own allowlist guidance for Firebase keys is:

  • Firebase Management API (firebase.googleapis.com)
  • Cloud Logging API (logging.googleapis.com)
  • Firebase Installations API (firebaseinstallations.googleapis.com)
  • FCM Registration API (fcmregistrations.googleapis.com)

If you enable additional Firebase products (Firestore/Storage/Auth/etc), expand the allowlist accordingly.

Development builds (optional)

By default, Happier avoids registering push tokens in __DEV__ to prevent accidental token churn during local dev.

To enable push token registration in dev builds, set:

  • EXPO_PUBLIC_ENABLE_DEV_PUSH_TOKEN_REGISTRATION=1

Custom mobile build (optional)

Build and install your own Happier app build for a self-hosted server (without publishing to app stores).

Updates

How updates work across Happier apps, CLIs, installers, Docker images, and release assets.

On this page

What notifications can doRicher notification detailsNotification preferencesWhat you need to configure1) Server (any deployment)2) Mobile app (iOS + Android)3) CLI (sender)Self-hosting checklistsRecommended (server-only)Multi-server behaviorAPI key restrictions (Android / Firebase)Application restriction (recommended)Finding the SHA-1 fingerprints you should addAPI restriction (recommended minimal allowlist for Cloud Messaging)Development builds (optional)