# Crit Alarm

> Self-hostable, ntfy-compatible alarm that rings through Do Not Disturb.

Crit Alarm is an alerting and incident management platform designed for homelabbers, solo developers, and site reliability engineers. It solves the bedside wake-up problem: when your primary database or critical service goes down at 3am, your phone rings until you wake up and acknowledge it.

Website: https://critalarm.app
API Reference: https://critalarm.app/docs/api
Documentation: https://critalarm.app/docs
GitHub Server: https://github.com/anvilnine/critalarm-server
GitHub App: https://github.com/anvilnine/critalarm-app

---

## 1. Product Overview

- **Rings Through Silent Mode**: On iOS, Crit Alarm uses Apple's official Critical Alerts entitlement to sound bedside sirens regardless of the physical mute switch or Focus filters. On Android, it uses a high-priority full-screen alarm channel.
- **Two-Stage Acknowledgment**:
  - Stage 1 ("I am up"): Tapping Acknowledge immediately silences the siren and starts a 10-minute desk timer.
  - Stage 2 ("At my desk"): If you do not resolve the incident at your desk within 10 minutes, the siren sounds again to prevent falling back asleep.
- **ntfy Protocol Ingress**: Drop-in compatible with ntfy publish endpoints (`POST /{topic}`) and header aliases (`Priority`, `Title`, `Tags`).
- **Privacy Architecture**: Self-hosted servers send zero alert text, zero topic names, and zero message payloads through the push relay. Only an opaque push token and an alert trigger ping are relayed to APNs.
- **Single Binary / Docker**: Written in Go with an embedded SQLite database. No external databases, no redis, no complex microservices.

---

## 2. Pricing Tiers

Crit Alarm uses flat, honest pricing with zero per-seat pager tax.

### Free Tier ($0/month)
- 5 active topics
- 1 critical topic with bedside siren
- 7 days of message history
- 30-second repeat loop until acknowledged
- Two-stage resolution with 10-minute desk timer
- Zero credit card required

### Pro Tier ($4/month flat)
- Unlimited topics
- Unlimited critical topics
- 90 days of message history
- Multi-device escalation after 5 minutes
- Automated telephone call escalation after 10 minutes
- Per-topic quiet hours and priority overrides
- Priority email and push support

### Self-Hosted ($0, Open Source AGPL-3.0)
- 100% free and open source forever
- All Pro features included
- Run on your own metal (VPS, Raspberry Pi, homelab NAS)
- Point the official mobile app directly at your custom domain
- Zero third-party telemetry, all data stored in local SQLite

---

## 3. Integrations

Crit Alarm integrates directly with any monitoring tool or script:
- **Uptime Kuma**: Add a webhook or ntfy notification channel pointing to `https://<server>/<topic>` with your topic bearer token.
- **Healthchecks.io**: Configure webhook pings for missed cron jobs.
- **Home Assistant**: Send critical security, leak, or temperature alerts via REST notify integration.
- **Curl / Shell / Cron**: A single curl command wakes your phone.

Example:
```bash
curl -X POST https://api.critalarm.app/t/prod-db \
  -H "Authorization: Bearer tk_xxxxxxxxxxxx" \
  -H "Priority: critical" \
  -H "Title: Primary DB Down" \
  -d "Connection pool exhausted. Failover initiated."
```

---

## 4. API Specification Summary

### 4.1 Publish Endpoints (ntfy-compatible)

- `POST /{topic}`: Publish notification or incident alert.
- `PUT /{topic}`: Alternative publish method.
- Authentication: `Authorization: Bearer tk_<token>` (required, no public topics).
- Priority values: `1` (min), `2` (low), `3` (default), `4` (high/time-sensitive), `5` (critical/alarm siren).
- Headers accepted: `X-Priority` / `Priority` / `prio` / `p`, `X-Title` / `Title` / `t`, `X-Tags` / `Tags` / `ta`, `X-Click` / `Click`, `X-Markdown` / `Markdown` / `md`.
- Response: `200 OK` with JSON `{ "id": "m_...", "time": 1757..., "topic": "...", "priority": 5, "incident_id": "inc_..." }`.

### 4.2 Polling Endpoint

- `GET /{topic}/json?poll=1[&since=<id|ts|duration>]`: Retrieve message backlog as newline-delimited JSON.

### 4.3 Incident Lifecycle & Management API (/v1/)

- `GET /v1/topics`: List registered topics and critical flags.
- `POST /v1/topics`: Create topic and issue topic token.
- `PATCH /v1/topics/{name}`: Update topic configuration (e.g. `critical: true`, repeat interval, desk timer).
- `DELETE /v1/topics/{name}`: Remove topic.
- `GET /v1/incidents`: List incidents by state (`open`, `acked`, `closed`, `expired`).
- `POST /v1/incidents/{id}/ack`: Stage 1 acknowledgment ("I'm up"), silences siren and starts desk timer.
- `POST /v1/incidents/{id}/close`: Stage 2 resolution ("At my desk").
- `POST /v1/test?topic={name}`: Trigger an immediate test alarm.
- `GET /v1/info`: Returns server version, mode (`selfhosted`, `relay`, `hosted`), base URL, and relay configuration.

---

## 5. Frequently Asked Questions

Q: Does Crit Alarm ring through silent mode?
A: Yes, Crit Alarm rings through silent mode and Do Not Disturb on both iOS (via Apple Critical Alerts) and Android (via full-screen alarm channels).

Q: Is Crit Alarm self-hosted?
A: Yes, the server is a single Docker container backed by local SQLite under the AGPL-3.0 license.

Q: Does it work with Uptime Kuma, ntfy, Healthchecks, and Home Assistant?
A: Yes, it implements standard ntfy publish endpoints and header aliases, making it a drop-in target.

Q: What does the push relay see?
A: The relay sees zero message contents, zero topic names, and zero notification text. It only receives opaque push tokens and trigger signals.

Q: How much does it cost?
A: 100% free for self-hosters and 5-topic hobby users; flat $4/month for managed Pro cloud hosting with no per-seat fees.