Alerts
The Alerts page sends you outbound notifications when something important happens at the observatory — a sequence finishes or fails, the sky becomes unsafe, or the safety monitor reports an error. It's how you find out about events without watching the UI. The AlertsManager subscribes to the event bus and, when an enabled condition fires, sends a message on every channel you've turned on.
There are two channels: email (over SMTP) and Pushover (over its HTTPS API). You can enable either, both, or neither. A single master switch (enabled) governs the whole feature — when it's off, nothing is ever sent, regardless of channel or condition settings.
The routing — which event maps to which condition and message — is unit-tested. The sending is real network I/O (smtplib for email, an HTTPS POST for Pushover) and can only be confirmed against your own SMTP server / Pushover account. Every send is wrapped so a failure is logged and never propagates back into the event bus.
Email (SMTP)
Tick on for email (email_enabled) and fill in your provider's SMTP details:
smtp_host— e.g.smtp.gmail.comsmtp_port— default587smtp_user/smtp_password— your SMTP credentials. The password is write-only: it is never sent back to the browser, and saving with the password field blank keeps the stored one.smtp_tls— use STARTTLS (default on)email_from— the From addressemail_to— comma-separated list of recipients
Email is only sent if smtp_host, email_from, and email_to are all set. If smtp_user is blank, the send skips the login step (for relays that don't require auth).
Pushover
Tick on for Pushover (pushover_enabled) and paste two values from your Pushover dashboard:
pushover_user_key— your user keypushover_app_token— your application/API token
Both are required. Failed sequences, stopped sequences, unsafe transitions and safety-monitor errors are sent at Pushover priority 1 (high); the routine ones (sequence complete, safe again) go at priority 0.
Emergency priority for critical alerts (new in v23, off by default). Tick Repeat critical alerts on the phone until acknowledged on the Alerts page (pushover_emergency_for_critical = true) and the notices Starship itself raises as critical — for example a park or close that could not be verified, or the report after a Windows restart — go out at Pushover emergency priority (2). The condition alerts in the list below (UNSAFE, sequence failed and so on) stay at high priority. The phone then repeats the alarm every pushover_emergency_retry_s seconds (default 60; Pushover's minimum is 30) until you acknowledge it, for at most pushover_emergency_expire_s seconds (default 3600; Pushover's maximum is 10800). The two timing keys are in the config file. Leave it off if a repeating alarm at night is not what you want.
Which events fire an alert
Each condition is an independent toggle. The defaults are chosen so you hear about the things that matter and aren't spammed by routine ones:
on_sequence_complete(default on) — a sequence finished successfullyon_sequence_failed(default on) — a sequence ended in a FAILED state (high priority)on_sequence_stopped(default on) — a sequence was stopped or halted, e.g. a meridian halt or a flip failure (high priority — a silent stop can quietly cost you the rest of the night)on_unsafe(default on) — the safety state changed to UNSAFE (high priority)on_safe(default off) — the safety state returned to SAFEon_safety_error(default off) — the safety monitor reported an error or stale data (high priority)
Conditions for the faults that quietly cost a night (all in [alerts]; set them in the config file if the page does not show them):
on_refocus_failed(default on) — a refocus during a run was rejected or failed; the run carries on at the old focuson_guiding_lost(default on) — guiding was lost, or PHD2 disconnected, while a guided run was active.guiding_lost_grace_s(default60) is how long a PHD2 disconnect must last before the alert is senton_filter_failed(default on) — a filter change failed and the frames that needed it were skippedon_retry_exhausted(default on) — the same step or device kept failing: one alert whennotify_after_consecutive_failures(default3) failures happen in a row, re-armed by the next successon_scheduler_empty_night(default on) — an hour or more of darkness produced no accepted frameson_blockscript_emergency(default on) — a blockscript session entered EMERGENCYon_blockscript_halted(default on) — a blockscript session is HALTED: the rig is safe and waiting for a personon_blockscript_dawn_timeout(default on) — a weather suspend lasted until dawn and the session endedon_blockscript_done(default off) — a blockscript session finished cleanlyon_blockscript_resume_cap(default on) — kept for old config files; nothing raises it any moreon_console_failure(default on; new in v23) — a park, roof close or cover close asked for at the Console failed, or its read-back did not confirm it; or a camera warm-up, camera cooling, cooler check or dome find-home job ended as failed. Sent at high priority. A job you cancelled is not a failure, and a click on a button for a device that is not connected is not alerted. Repeats of the same failure are held to one per cooldown window
The sequence conditions are driven by sequencer.state events; the safety conditions by safety.state_changed; and the safety-error condition by solo.error / solo.stale. When a sequence fails or is stopped, the alert includes a Reason line if the underlying event carried one (for example the halt or flip-failure detail). The UNSAFE message carries the verdict's reasons; UNKNOWN safety verdicts are treated as unsafe for alerting purposes.
Send a test alert
The Send test alert button dispatches a fixed test message on every enabled channel so you can confirm the wiring end-to-end. It requires the master switch to be on. The result reports per-channel success, so you can see exactly which channel delivered and which failed and why.
Saving and when changes take effect
The Alerts page has its own Save endpoint. On save the config is written to your config.toml and the live AlertsConfig is updated in place. The AlertsManager reads the config fresh on every event, so saved changes take effect immediately — no restart needed.
Edge-firing and de-duplication
Safety alerts are edge-triggered: the manager tracks the previous safe/unsafe state and only sends on a genuine transition (safe → unsafe, or unsafe → safe), so repeated readings of the same state do not re-send.
On top of that there is a time-based rate limit, on by default (rate_limit_enabled = true, cooldown_s = 900, i.e. 15 minutes):
- A repeat of the same alert (same condition and subject) inside the cooldown window is suppressed; a different failure sends at once.
- The routine conditions (sequence complete, safe again) send at most once per window per condition.
- Never rate-limited: the UNSAFE alert, the safety-monitor error, a blockscript EMERGENCY / HALTED / ended-at-dawn alert, critical alerts, and the test send.
- A safety-monitor error (
on_safety_error) sends one alert per outage and then a periodic reminder while the outage lasts, not one per failed poll.
Set rate_limit_enabled = false or cooldown_s = 0 to turn the rate limit off. A suppressed alert is written to the log.
Endpoints
GET /api/alerts/config— returns the current config. The SMTP password is blanked; asmtp_password_setflag tells the UI whether one is stored.POST /api/alerts/config— saves the config and persists it toconfig.toml.POST /api/alerts/test— runssend_test()and returns the per-channel result.
Caveats
- Master switch first. With
enabledoff, no condition and no test alert sends anything. - A channel must be on. With neither
email_enablednorpushover_enabledset, a dispatch returnsno channel enabled. - Real delivery is your account's job. The routing is tested; SMTP/Pushover delivery depends on correct credentials and a reachable server. Always run a test send after configuring.
- Send failures are silent to the night. A failed alert is logged but never interrupts the bus or the sequence — so don't treat a missing alert as proof nothing happened.
- A failed alert is tried again (v23). An alert that fails on every enabled channel is queued and re-sent: after 30 s, 1, 2, 5 and 10 minutes, then every 15 minutes, for at most 12 tries or 24 hours. A late one is marked
[delayed - first tried HH:MM]. The queue (at most 50 alerts) is kept in a file, so it survives a restart of Starship or the PC. If alerts are switched off when a queued alert comes due, it is written to the log and dropped. See the Windows restarts and crashes topic. - An alert at start after an unclean stop (v23). When the last run of Starship was ended by a Windows restart, a closed console window, or without a clean stop at all, the next start sends one critical alert saying so.
Configuration
These settings live in the [alerts] section of config.toml and mirror the page controls. See the Settings and Config file topics for how the file is loaded and saved.