roostDocs
GitHub ↗

Use Roost

Push notifications#

In Settings → Notifications, choose Enable on this device and allow the browser permission prompt. Each browser or installed PWA subscribes separately. Choose Disable on this device to stop delivery to just that browser or PWA.

The notification switches are saved on your Roost server and apply to all devices:

  • Notifications enabled stops all new notifications when turned off. Device subscriptions and your choices below are kept for when you turn it back on.
  • Turn completed alerts you when a conversation or scheduled task finishes.
  • Agent updates allows agents to send useful updates during a task, such as a confirmed delivery or a change they were asked to track.
  • Needs attention alerts you about approval requests and failed or interrupted work.

All switches start on; device delivery still requires enabling that device. Turning off turn-completion alerts does not turn off agent updates or requests needing attention. Notifications already handed to a push provider can still arrive after you turn a switch off.

Notifications name the agent and preview useful content: the final response, failure reason, approval request, or an update written by the agent. For example, Shoppy · Package delivered might say “Your order was delivered at 2:14 PM. The carrier says it is by the front door.” These previews can appear on your lock screen. Tapping one opens the agent's conversation; it does not approve anything.

Quiet automations that return ROOST_NO_UPDATE stay quiet. Cancelled runs and intermediate specialist delegations do not send completion notifications. When an agent explicitly posts an update and agent updates are enabled, Roost skips the routine completion alert for that run.

Updates from agents#

Agents have a roost_notify tool for updates within the work you requested. For example, ask Shoppy to check a delivery and notify you when it arrives. A recurring check still needs an automation; sending a notification does not create one. The tool accepts a short title, useful body, and a stable request ID. The sender and conversation link come from the running agent.

Updates are saved in the conversation even when push notifications are off or no devices are subscribed. Retrying the same request does not send another alert. Agents cannot change your notification preferences. The tool reports whether a push provider accepted the notification; it cannot confirm that a device showed it or that you read it.

Server setup#

For a source installation, set a contact address for your push sender before starting Roost:

ROOST_PUSH_SUBJECT=mailto:you@example.com corepack pnpm start

For a packaged systemd installation, add the setting to the service instead of only exporting it in your terminal:

sudo systemctl edit roost-$(id -u).service

Add this drop-in, replacing the example with your contact address:

[Service]
Environment="ROOST_PUSH_SUBJECT=mailto:you@example.com"

Wait for active work to finish, then run roost server stop followed by roost server start to apply the service environment. Stopping interrupts active runs; changing the setting itself does not.

An HTTPS contact page is also accepted. This identifies your Roost installation to browser push services; it is not an email delivery address. Use your own contact information. A missing or invalid setting disables notification setup.

Roost generates its VAPID signing keys once in $ROOST_DATA_DIR/notifications/vapid.json (.roost/notifications/vapid.json by default), with private directory/file permissions. Keep this file with your data backups and do not publish it. Browser subscriptions are stored in the Roost database. Losing the signing keys requires devices to disable and enable notifications again. Only the public key is sent to the browser.

The browser needs a secure context: HTTPS for remote access, or localhost during development. Keep Roost behind the same authenticated private proxy you use for remote access; push adds no public inbound endpoint. On iPhone and iPad, add Roost to the Home Screen and enable notifications from the installed app. Permission is requested only when you press the enable button. If notifications were blocked, change the browser/device permission, reload Roost, and enable them again.

The server needs outbound HTTPS access to the browser's push provider. Roost currently accepts Google FCM, Mozilla, Apple Web Push, and Windows notification endpoints. Other endpoint hosts are rejected to prevent arbitrary outbound requests. No Firebase project or paid notification service is required.

Delivery behavior#

Roost and its host must remain running to finish work and send notifications. The browser/PWA can be closed. Delivery is best effort: server failures never fail agent work, missed sends are not retried, and the push service retains a sent notification for up to one hour. Device permissions, Focus modes, network access, and the operating system can delay or prevent display. Check the conversation for the durable result or pending approval.

Expired subscriptions (provider HTTP 404/410) are removed automatically. Transient delivery failures keep the subscription for the next update and log only a generic message, without subscription URLs, keys, or provider responses. If a browser rotates or loses its subscription, enable notifications again in Settings. Subscriptions are limited to 32 devices per installation.

Implementation references: Web Push library, browser subscription API, and Apple Web Push.