---
url: https://clusto.app/docs/background-notifications.md
description: >-
  Android background notifications - poll the cluster on a battery-friendly ~15
  min timer and surface anything you missed while the app was closed.
---

# Background Notifications (Android)

Clusto's in-app notifications only fire while the app is open and connected. On
Android, **background notifications** close that gap: the app briefly wakes on a
timer, connects to your cluster, and raises a native notification for anything
that happened while it was closed or backgrounded - a finished terminal agent
or durable chat, a scheduled task that succeeded or failed, or a session
waiting on you.

This is opt-in and battery-friendly. Clusto does **not** hold a constant
connection; it connects for a moment roughly every 15 minutes, checks for missed
alerts, and disconnects.

## Turning it on

Open **Settings -> Notifications** on the Android app. Under **Background
notifications (this device)**, enable **Check for missed notifications while the
app is closed**.

The toggle works only on Android, where the native scheduling support exists;
elsewhere the section is shown greyed out. On desktop and in the web client the app relies on the normal in-app / OS alerts
while it is running (see [Agent Waiting Marker](/agent-attention)), so there is
no equivalent toggle there.

If alerts do not arrive, open **Settings > Node Doctor**. Its **This device** row
shows whether system notification permission, alert popups and Android background
checks are on, and **Send test notification** raises a sample alert. See
[Node Doctor](/knowledge#node-doctor).

## Unencrypted LAN addresses need your OK

The background check is a plain HTTP request that carries your token. It goes
out without asking only where that is safe: this device (loopback), your
Tailscale network (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`, `*.ts.net`), or
`https://` to a node with a certificate for its DNS name. When the profile can
only reach a node over plain HTTP on another network (a `192.168.x.x` address,
say), the check would send the token in clear on every poll, so Clusto skips it
and **Settings -> Notifications** shows that background notifications are
paused, with an **Allow unencrypted polls to ...** button per host.

Allowing a host is saved with the profile (it syncs to your own devices, never
to a team vault) and can be undone with **Stop unencrypted polls**. The node
must also accept unencrypted connections from that network
(`[transport] plaintext_networks`), or every poll is refused with `403`. The
refusal arrives after the request, headers included, has been sent, so a poll to
a network the node refuses still exposes the token once per poll. An allowed
address is polled on whatever network the phone is on, and a private address
such as `192.168.1.5` can belong to another device on a cafe or office
network, which would then receive your token. Prefer Tailscale or a node
certificate. The Android check cannot pin a node's key like the app does, and it
cannot use the Clusto Tunnel, so a profile that reaches a node only through the
tunnel is not polled. See
[Node Identity & Pairing](/node-identity#unencrypted-connections).

A prompt you have already answered no longer reaches the background check: once
the agent continues, the alert is marked answered in the
[notification center](/notification-center) and the phone does not raise it.

## What you get notified about

While the app is closed, a background check surfaces the same events the app
would have alerted you to live:

* **A terminal agent or durable chat finished** - a session went idle or a chat
  reply became ready.
* **A scheduled task succeeded or failed** - honouring the per-task
  **Notify on success** / **Notify on failure** opt-ins (see [Tasks](/tasks)).
  A task with neither flag set stays silent.
* **A session is waiting for you** - the same "needs input" signal that drives
  the `?` marker (see [Agent Waiting Marker](/agent-attention)).
* **A new report** - posted by an agent or script to [Reports](/reports),
  filtered by the report rules in **Settings -> Notifications -> Reports**
  (a default rule plus per-project overrides). Tap it to open the report.
* **A GitHub pull request alert** - a review requested from you, failed checks
  on a pull request you wrote, or one of your pull requests approved, merged or
  closed (see [GitHub](/github#notifications)). Tap it to open the pull request.
  Each kind has its own switch under **Settings -> Notifications**.

Each notification carries a title and body and, where relevant, targets the
terminal session or chat it relates to. Tap the notification itself to open
that target; Clusto does not add a separate action button on Android.

## Timing: expect up to ~15 minutes

The ~15 minute cadence is a floor imposed by Android, not a setting. Clusto uses
an **inexact repeating alarm**, which Android is free to delay and batch,
especially under Doze (the OS's idle power-saving mode). So a missed alert can
arrive up to about 15 minutes late, sometimes more if the device has been idle
for a long stretch.

This is a deliberate trade-off: a constant push connection would drain the
battery, while a periodic wake keeps power use negligible. If you need
to-the-second alerts, keep the app open in the foreground, where in-app
notifications fire immediately.

## No double alerts while another client is connected

If any Clusto app is connected to the cluster - say Clusto is open on your desktop -
that client already receives every alert as a live push. The background poll
stays silent for as long as such a client is connected, so your phone does not
buzz for things you are already looking at elsewhere. The poll cursor still
advances during the quiet period; those alerts are considered delivered and do
not arrive late once the other client disconnects.

Two details:

* Only **app** clients count. A transient `clusto` CLI invocation does not
  suppress background notifications.
* Answering a waiting session clears its pending `attention` records from the
  durable log immediately, so a prompt you resolved on the desktop cannot
  re-notify your phone on the next poll even if the desktop disconnects right
  after.

## Battery saver: background idle sleep (mobile)

Related to, but separate from, background notifications: on phones and tablets
the app has a **battery saver** (**Settings -> This device -> Battery**, touch devices only). When the
app has been in the background for the configured idle window (default **15
minutes**), it disconnects from the daemon - stopping the Android keep-alive
foreground service, its ongoing "Keeping your sessions connected" notification,
and the WebSocket keepalive pings that would otherwise hold the radio awake.
The app reconnects automatically the moment you return to it.
After the connection and initial data recovery complete, Clusto keeps the
connect/reconnect loading indicator visible only briefly to avoid a flash. The
artificial minimum is capped at 750 ms, so recovered content becomes usable
promptly after reopening or resuming the app.

On Android the countdown runs natively (a one-shot `AlarmManager` alarm),
because Android freezes a backgrounded WebView's JS timers - a JS-only timer
would never fire exactly when it matters. The alarm is a non-wakeup alarm: if
the device is in deep sleep at the deadline, the disconnect happens on the next
natural wake instead of waking the CPU just to save power.

While asleep the app holds no connection, so enable background notifications if
you still want missed-alert delivery during that window.

## Cluster-wide coverage

The background check polls a single node - whichever one your app's **active
profile** points at. That node aggregates missed notifications from the **whole
cluster** before answering, so a task failure, an idle terminal agent, or a
completed chat on any node still reaches your phone through the one node you
poll. You do not need to poll every node individually.

## How it works

The feature has two halves: a durable notification log the daemon keeps, and a
native Android poller that reads it.

### Daemon: durable notification log

Every alert the daemon fires is appended to a durable log (a SQLite
`notifications` table) so a client that was
offline when the alert fired can still see it on its next poll. The log is
bounded: rows older than **7 days**, or beyond the newest **500**, are pruned
after each insert.

Each record carries a stable `id` (clients dedupe on it across polls), the
firing time in Unix milliseconds, a machine-readable `kind`, an optional
`session_id` tap-to-open target, the firing `node_id`, and a `title` / `body`.
Terminal targets store a session UUID. Chat targets store `chat:<uuid>` so
opening the notification routes to the originating chat.

The `kind` is one of:

| `kind` | Meaning |
|---|---|
| `agent_idle` | A terminal agent went idle or a durable chat reply completed |
| `attention` | A session is waiting for the user (the `?` state) |
| `task_success` | A scheduled task completed with exit 0 |
| `task_failure` | A scheduled task failed (non-zero exit or timeout) |
| `report` | A new report was posted to [Reports](/reports) |
| `github_review_requested` | A review was requested from you on a [GitHub](/github) pull request |
| `github_checks_failed` | Checks failed on a pull request you wrote |
| `github_pull_update` | A pull request you wrote was approved, merged or closed |

### HTTP endpoint

The Android poller reads the log over a small authenticated HTTP endpoint:

```
GET /notifications?since_ms=<unix_ms>
```

* Authenticate with the daemon token as `Authorization: Bearer <token>`. The
  cluster token is also accepted. A `?token=` query parameter is not accepted,
  so the credential never lands in access logs or proxies.
* The response is `{ "now_ms": <server_time>, "items": [ ...NotificationRecord ] }`,
  where `items` are the notifications fired after `since_ms`, aggregated across
  the cluster.
* The client persists the returned `now_ms` as its next `since_ms` cursor, so
  each poll only returns what is new since the previous one.
* While any app client is connected anywhere in the cluster, `items` is empty
  (see "No double alerts" above); `now_ms` still advances the cursor.
* A device can switch off the GitHub alert kinds for its own poll by
  adding `github_review_requested=off`, `github_checks_failed=off` and/or
  `github_pull_update=off` to the query, for example
  `GET /notifications?since_ms=<unix_ms>&github_review_requested=off`. The
  [Azure DevOps](/azure-devops) and factory (`factory_waiting_owner`,
  `factory_pull_ready`) kinds can be muted the same way. No other kind can, and
  only the value `off` mutes. The app sets them from the per-device switches
  under **Settings -> Notifications**.
* The device's report rules ride along on the same poll:
  `report_default=all|warnings|errors|off` sets the default rule and
  `report_projects=<uuid>:<mode>,...` adds per-project overrides. A poll without
  `report_default` receives every report alert.

The same aggregation is available over the WebSocket protocol via
`ClientMessage::GetNotifications { since_ms }` ->
`ServerMessage::Notifications { items, now_ms, active_clients }`, which the
polled node uses to fan out to its peers: each peer answers with its own log
slice and its local count of connected app clients, and the polled node merges
the items and sums the counts (see [Protocol](/protocol)).

### Android native side

The native scheduling is generated into the Android project at build time. It
wires up:

* An **AlarmManager** inexact-repeating alarm that wakes the app roughly every
  15 minutes.
* A **BroadcastReceiver** (`ClustoBackgroundNotifyReceiver`) that runs on each
  alarm: it does the `GET /notifications` request with the stored cursor and
  posts a native notification for each new item.
* A **boot receiver** that re-arms the alarm after the device reboots, so the
  feature keeps working across restarts without reopening the app.

Configuration (enabled flag, base URL, token, and the `since_ms` cursor) lives
in Android **SharedPreferences**, written when you toggle the setting and read by
the receiver on each wake.
