Repository navigation
Features and Workflows
This guide explains where URSA's tools live and when they are useful. The repository
docs/ folder is the technical reference; this page stays focused on tasks and examples.
Home reads the latest encrypted snapshot for every saved server without keeping a permanent socket open to all of them. Tap Refresh all when you want a bounded live check. A server card says whether its data is live, freshly refreshed, cached, stale, or unavailable.
Example: if a home lab and a hosted server both have failures, Home shows the total affected count first. Expand either card for connection health, then open only that server's affected monitors or incident history.
Monitors belongs to the active server. Search by name, type, tag, group, address, or parent; combine status filters; change sort order; save a view; or use compact rows. Long-press or enter selection mode for confirmed bulk state changes and previewed common-field edits.
Each monitor has three sections:
- Overview - current status, freshness, response time, group/tag context, favourite state, and pause/resume.
- History - quick windows or an exact range from the last 30 days, coverage, heartbeat rows, chart, transitions, certificate details, and CSV/HTML exports.
- Configuration - the safe native editor, clone/copy/preset actions, and a clear Kuma browser fallback when a field cannot be round-tripped safely.
Example: choose an exact overnight interval, review the observed coverage, then save that same bounded result as CSV or accessible HTML. The export excludes addresses, messages, credentials, access headers, and notification data.
Incidents deliberately separates two sources:
- Kuma history groups monitor transitions into active and resolved outages and adds observed downtime, MTTR, flakiest-monitor, and coverage summaries.
- Device alerts groups the Android decisions URSA made for received, delayed, delivered, repeated, acknowledged, snoozed, suppressed, correlated, and recovered events.
Local notes are encrypted. Sharing uses a redacted summary, not a raw event dump. Public status-page incidents remain server-backed Kuma records and are never invented from local alert groups.
Browse is searchable and divided into three sections:
- Operations - maintenance, public status pages, notifications, and monitor views.
- Insights and reports - certificates, domains, event log, 30-day aggregate, pinned live panel, history/SLA reporting, and credential-free inventory export.
- Manage - monitor presets, group wizard, validated CSV/TXT import, saved servers, and device settings.
The local Browse search indexes safe names and labels only. It does not index credentials, access-header values, full URLs, or incident and maintenance bodies.
URSA can create or safely edit every verified 2.5.6 monitor type within its declared native boundary. Saved secrets are presence-only: leave a secret field blank to keep the server value, or enter a replacement. Unknown fields are protected by fetching a fresh full object before save and rejecting unrelated drift.
Useful workflows include:
- Clone a monitor into an inactive, credential-free draft.
- Save an eligible draft as one of 50 encrypted local presets.
- Copy a sanitized inactive draft to another saved server for review.
- Import up to the documented row limit from CSV or tab-delimited text after a dry run.
- Build a group and move existing children through a previewed, resumable sequence.
- Export a deterministic credential-free active-server inventory.
None of these actions silently creates a monitor from a preset or transfers a secret.
Browse > Notifications manages one marked Kuma Webhook for URSA's UnifiedPush endpoint. It can assign the provider to existing monitors and optionally make it the default for new ones. Local policy adds per-monitor modes, severity, delay/repeat, quiet hours, dependency suppression, group N-of-M thresholds, alert grouping, and cautious shared- failure hints without changing Kuma's own behavior.
Use Test phone notification before Test through Kuma. The first isolates Android; the second includes Kuma and the distributor.
Connections can use HTTPS, explicit plain HTTP, an opt-in self-signed certificate, and up to eight encrypted custom request headers. The same connection policy applies to Socket.IO polling, WebSocket upgrades, authenticated requests, and an exactly matching saved status-page URL.
On Android 17, direct LAN targets, Tailscale 100.64.0.0/10 addresses, and .ts.net
MagicDNS names can trigger the scoped local-network permission flow.
The phone app includes configurable home-screen widgets, a fleet Quick Settings tile, app shortcuts, scoped deep links, biometric/device-credential lock, local certificate and slow-response reminders, a manual update check, and an optional always-on glance display. Widgets are encrypted, exact-size, and show bounded cached data.
The separate Wear APK supports a public status-page mode on its own. GitHub phone builds can additionally pair an encrypted private session with a same-signed watch for confirmed pause/resume actions. See Wear OS.
Browse > Settings > Screenshot protection offers:
- Off - screenshots and screen recording are allowed throughout URSA.
- Sensitive screens only - credentials, tokens, access headers, and notification setup stay protected while ordinary dashboards remain capturable.
- Always - the whole app remains protected.
Existing installs preserve the previous secure behavior until the user changes it. New or unreadable preference state also fails closed to Always.