# OnCallAlert > OnCallAlert is a self-hosted on-call alerting and incident response platform backed by PostgreSQL. It features native mobile apps with Do Not Disturb override, unlimited free viewer seats, zero-telemetry BYOK AI incident triage, and integrations for Prometheus, Grafana, Datadog, and Terraform. OnCallAlert runs as a single lightweight Docker container backed by PostgreSQL 16+. It provides escalation policies, schedules, rotations, phone call and SMS fallback, out-of-band dead-man monitoring, and an official Model Context Protocol (MCP) server for autonomous AI agents. ## Getting Started - [Docker Deployment](https://oncallalert.dev/docs/markdown/docker-deployment.md): Quickstart instructions for running OnCallAlert via Docker, creating administrators, and server activation. - [Environment Variables](https://oncallalert.dev/docs/markdown/configuration.md): Complete reference for server configuration environment variables, ports, and operational flags. - [Database Setup](https://oncallalert.dev/docs/markdown/postgres.md): PostgreSQL requirements, pgcrypto extension, encryption at rest, and zero-downtime database switchover. - [Runtime Configuration Reference](https://oncallalert.dev/docs/markdown/configuration-reference.md): Every runtime setting with type, default and description, plus CLI, GraphQL and REST examples. Machine-readable JSON Schema: https://oncallalert.dev/schemas/config.json ## Migration - [Import from PagerDuty, JSM or Opsgenie](https://oncallalert.dev/docs/markdown/migration.md): Non-destructive, read-only migration of users, rotations, schedules, and escalation policies. ## Integrations & APIs - [Grafana Webhooks](https://oncallalert.dev/docs/markdown/grafana.md): Setting up Grafana webhook contact points, alert payload mapping, and automatic incident resolution. - [Prometheus Alertmanager](https://oncallalert.dev/docs/markdown/prometheus.md): Integrating Prometheus Alertmanager webhooks, deduplication by fingerprint, and auto-resolution. - [Datadog Webhook](https://oncallalert.dev/docs/markdown/datadog.md): Forwarding Datadog monitors and alerts via custom webhook templates and generic API ingestion. - [Generic Alert Ingestion API](https://oncallalert.dev/docs/markdown/generic-api.md): High-throughput JSON REST API to programmatically trigger, deduplicate, and resolve incidents. ## Infrastructure as Code - [Terraform, OpenTofu & Pulumi](https://oncallalert.dev/docs/markdown/iac.md): Declaratively managing services, schedules, escalation policies, rotations, and integration keys. ## AI Assistants & Integrations - [OnCallAlert MCP Server](https://oncallalert.dev/docs/markdown/mcp.md): Model Context Protocol server exposing alert queries, acknowledgement, escalation, and resolution to AI tools. - [Ask AI for Alerts](https://oncallalert.dev/docs/markdown/ask-ai.md): Zero-telemetry bring-your-own-key (BYOK) AI incident summaries supporting OpenAI, Anthropic, Ollama, and Gemini. ## Operations & Reliability - [User Roles](https://oncallalert.dev/docs/markdown/roles.md): Roles matrix (Owner, Admin, On-call, Viewer) and policy on unlimited free viewer seats. - [Dead-Man Switch](https://oncallalert.dev/docs/markdown/deadman.md): Automated out-of-band heartbeat monitoring to detect silent infrastructure and server outages. ## Mobile Applications - [iOS & Android Setup](https://oncallalert.dev/docs/markdown/mobile-setup.md): Installing the native mobile apps (Android live on Google Play, iOS live on the App Store), connecting self-hosted instances, and pairing push contact methods. - [DND Override Permissions](https://oncallalert.dev/docs/markdown/dnd-permissions.md): Configuring full-screen emergency incoming calls to bypass Do Not Disturb filters and save telephony bills. ## In-App Admin Settings Reference | Parameter | Type | Default | Scope | Description / Impact | |---|---|---|---|---| | `General.ApplicationName` | String | `"OnCallAlert"` | Public | System name in page titles, emails, and TTS voice intros. | | `General.PublicURL` | String | *None* | Public | Base URL for links. (Overridden by `ONCALLALERT_PUBLIC_URL`). | | `General.GoogleAnalyticsID` | String | *None* | Public | Google Analytics 4 measurement ID. | | `General.NotificationDisclaimer` | String | *None* | Public | Legal disclaimer on user profile pages. | | `General.DisableMessageBundles` | Boolean | `false` | Public | Disables grouping consecutive alerts into bundles. | | `General.ShortURL` | String | *None* | Public | Short URL prefix for SMS notification links. | | `General.DisableSMSLinks` | Boolean | `false` | Public | Strips all URLs from outbound SMS to prevent carrier filtering. | | `General.DisableLabelCreation` | Boolean | `false` | Public | Blocks creation of arbitrary new service labels. | | `General.DisableCalendarSubscriptions`| Boolean | `false` | Public | Deactivates all iCalendar (ICS) schedule export feeds. | | `Services.RequiredLabels` | []String | `[]` | Public | Mandatory labels required when creating any new service. | | `Maintenance.AlertCleanupDays` | Integer | `0` (Off) | Public | Days to retain closed alerts before permanent deletion. | | `Maintenance.AlertAutoCloseDays` | Integer | `0` (Off) | Public | Inactivity days before unacknowledged alerts auto-close. | | `Maintenance.AutoCloseAckedAlerts` | Boolean | `false` | Public | Applies auto-close to acknowledged alerts as well. | | `Maintenance.APIKeyExpireDays` | Integer | `0` (Off) | Public | Days of inactivity before unused calendar keys expire. | | `Maintenance.ScheduleCleanupDays` | Integer | `0` (Off) | Public | Days to retain historical on-call shift records. | | `Auth.DisableBasic` | Boolean | `false` | Public | **Killswitch**: Disallows username/password login; enforces SSO. | | `GitHub.Enable` | Boolean | `false` | Public | Enables GitHub OAuth authentication. | | `GitHub.ClientID` / `ClientSecret` | String | *None* | Secret | GitHub OAuth application credentials. | | `GitHub.NewUsers` | Boolean | `false` | Internal | Permits automatic user creation via GitHub login. | | `GitHub.AllowedUsers` / `AllowedOrgs` | []String | `[]` | Internal | Whitelist of GitHub usernames or org/team memberships. | | `OIDC.Enable` | Boolean | `false` | Public | Enables OpenID Connect (OIDC) SSO. | | `OIDC.IssuerURL` | String | *None* | Internal | Discovery issuer URL (Google, Okta, Azure AD, Keycloak). | | `OIDC.ClientID` / `ClientSecret` | String | *None* | Secret | OIDC client credentials. | | `OIDC.Scopes` | String | `"openid profile email"` | Internal | Requested OAuth scopes. | | `OIDC.OverrideName` | String | `"OIDC"` | Public | Custom display label on the login button. | | `Twilio.Enable` | Boolean | `false` | Public | Enables Twilio voice calls and SMS dispatch. | | `Twilio.AccountSID` / `AuthToken` | String | *None* | Secret | Primary Twilio API credentials. | | `Twilio.AlternateAuthToken` | String | *None* | Secret | Secondary token for zero-downtime credential rotation. | | `Twilio.FromNumber` | String | *None* | Public | Outbound caller ID in E.164 format. | | `Twilio.MessagingServiceSID` | String | *None* | Public | Twilio Messaging Service SID (replaces FromNumber for SMS). | | `Twilio.VoiceName` / `VoiceLanguage` | String | *None* | Internal | Amazon Polly voice and language tag for TTS voice calls. | | `Twilio.DisableCallProcessing` | Boolean | `false` | Public | **Emergency Killswitch**: Halts all voice phone call processing. | | `Twilio.DisableSMSContactMethod` | Boolean | `false` | Public | **Emergency Killswitch**: Disables SMS contact option globally. | | `Twilio.DisableTwoWaySMS` | Boolean | `false` | Internal | **Killswitch**: Disables SMS reply codes ('1' to Ack, '2' to Close). | | `Alerts.HighPriorityLabelKey` | String | *None* | Public | Metadata key flagging high-priority alerts (e.g. `severity`). | | `Alerts.HighPriorityLabelValue` | String | *None* | Public | Value matching high priority (e.g. `critical`, `high`). | | `Alerts.HighPriorityEscalationContactTypes` | []String | `[]` | Public | Channels alerted on unacked high-priority breach (`voice`, `sms`, `mobile`, `email`, `slack`, `webpush`). | | `Alerts.HighPriorityEscalationDelayMinutes` | Integer | `5` | Public | Elapsed minutes before high-priority escalation fires (min: 1). | | `Alerts.HighPriorityDedupeWindowMinutes` | Integer | `2` | Public | Deduplication window preventing double-paging for same alert. | | `WebPush.Enable` | Boolean | `false` | Public | Enables W3C VAPID browser push notifications. | | `WebPush.VAPIDPublicKey` | String | *None* | Public | Base64 URL-safe unpadded public key. | | `WebPush.VAPIDPrivateKey` | String | *None* | Secret | Private key for signing VAPID push messages (stored encrypted). | | `WebPush.SubscriberEmail` | String | *None* | Public | Contact URI (`mailto:admin@example.com`) in VAPID claims. | | `Mobile.Enable` | Boolean | `false` | Public | Enables mobile push routing via OnCallAlert Relay. | | `Mobile.RelayURL` | String | `"https://relay.oncallalert.dev"` | Public | Base URL of the push relay gateway. | | `Mobile.RelayAPIKey` | String | *None* | Secret | Push relay authentication secret. | | `Deadman.Enable` | Boolean | `false` | Public | Enables out-of-band SaaS heartbeat watchdog. | | `Deadman.IntervalSeconds` | Integer | `300` | Public | Heartbeat ping interval in seconds (300 to 3600). | | `Deadman.MissCount` | Integer | `3` | Public | Consecutive missed heartbeats before alerting admin phones (1 to 10). | | `AI.Enable` | Boolean | `false` | Public | Enables Ask AI incident triage. | | `AI.Provider` | String | *None* | Internal | Provider: `openai`, `anthropic`, `ollama`, or `openai-compatible`. | | `AI.Model` | String | *None* | Internal | Model name (e.g. `gpt-4o-mini`, `claude-3-5-haiku-20241022`, `llama3.2`). | | `AI.BaseURL` | String | *None* | Internal | Custom API URL (required for `openai-compatible`). | | `AI.AutoTriage` | Boolean | `false` | Internal | Automatically summarizes every new incoming alert. | | `AI.MaxPerHour` | Integer | `30` | Internal | Hourly rate limit protecting against alert storm LLM costs. | ## MCP Server Tools (All 14 Tools) | Tool | Mutating | Allowed Roles | Description | Inputs | |---|---|---|---|---| | `list_alerts` | No | All (Viewer, User, Admin, Owner) | Lists alerts sorted newest first. | `service_id`, `status` (open/acknowledged/closed), `since`, `until`, `search`, `first` (default 15, max 100), `after` | | `get_alert` | No | All | Retrieves alert details, service name, and up to 50 recent events. | `id` (Integer, required) | | `ack_alert` | **Yes** | User, Admin, Owner | Acknowledges up to 50 alerts in batch, freezing escalation timers. | `ids` (List of Integers, 1 to 50, required) | | `resolve_alert` | **Yes** | User, Admin, Owner | Closes up to 50 alerts in batch. | `ids` (List of Integers, 1 to 50, required) | | `escalate_alert` | **Yes** | User, Admin, Owner | Immediately escalates an alert to the next escalation policy tier. | `id` (Integer, required) | | `create_alert` | **Yes** | User, Admin, Owner | Creates an alert on a service, paging the active responder. | `service_id` (required), `summary` (required), `details` (optional), `dedup` (optional) | | `get_oncall` | No | All | Looks up who is on call right now (or at past/future `at` time for schedules). | Exactly one of: `service_id`, `escalation_policy_id`, `schedule_id`; optional `at` (schedules only) | | `list_schedules` | No | All | Lists on-call schedules with search. | `search`, `first`, `after` | | `get_schedule` | No | All | Gets schedule with shifts, rules, and overrides in time window. | `id` (required), `start`, `end` | | `create_user_override` | **Yes** | User, Admin, Owner | Adds, removes, or swaps an on-call responder on a schedule. | `schedule_id` (required), `start` (required), `end` (required), `add_user_id`, `remove_user_id` | | `list_services` | No | All | Lists services with escalation policies and maintenance flags. | `search`, `first`, `after` | | `search_users` | No | All | Searches users alphabetically by name. | `search`, `first`, `after` | | `get_user` | No | All | Gets user profile, contact methods, and active on-call assignments. | `id` (UUID, required) | | `whoami` | No | All | Returns authenticated token identity and role. | None (`{}`) | ## Infrastructure as Code (IaC) Reference - **Provider**: `OnCallAlert/oncallalert` - **Supported Platforms**: Terraform, OpenTofu, Pulumi - **Authentication**: `url` (or `ONCALLALERT_URL`) and `token` (or `ONCALLALERT_TOKEN`, requires Admin scope). ### Resources 1. `oncallalert_escalation_policy`: Multi-tier escalation policies with `repeat` count and ordered `steps` (`delay_minutes`, `actions` with `type` and `args`). 2. `oncallalert_rotation`: Automated shift rotations with `type` (`hourly`, `daily`, `weekly`, `monthly`), `shift_length`, `start` anchor timestamp, `time_zone`, and ordered `user_ids`. 3. `oncallalert_schedule`: Schedule container defined with canonical `time_zone`. 4. `oncallalert_schedule_rule`: Time window rules targeting `rotation` or `user` with `start` (HH:MM), `end` (HH:MM), and `weekdays` filter. 5. `oncallalert_user_override`: Bounded shift coverage overrides (`add_user_id`, `remove_user_id`, `start`, `end`). 6. `oncallalert_service`: Operational services bound to an `escalation_policy_id`. 7. `oncallalert_service_label`: Key-value service tags (`key`, `value`, `service_id`). 8. `oncallalert_integration_key`: Inbound webhook tokens (`type`: `generic`, `grafana`, `site24x7`, `prometheusAlertmanager`, `email`, `universal`). ### Data Sources - `oncallalert_user`: Lookup by `email`. Exports `id`, `name`, `role`. - `oncallalert_service`: Lookup by `name`. Exports `id`, `description`, `escalation_policy_id`. - `oncallalert_schedule`: Lookup by `name`. Exports `id`, `description`, `time_zone`. - `oncallalert_escalation_policy`: Lookup by `name`. Exports `id`, `description`, `repeat`. - `oncallalert_rotation`: Lookup by `name`. Exports `id`, `description`, `time_zone`, `type`. ### Import Syntax - `oncallalert_escalation_policy.`: `` - `oncallalert_rotation.`: `` - `oncallalert_schedule.`: `` - `oncallalert_schedule_rule.`: `/` - `oncallalert_user_override.`: `` - `oncallalert_service.`: `` - `oncallalert_service_label.`: `/` - `oncallalert_integration_key.`: `` ## User Roles & Seat Model - **Owner**: Full administrative access plus ability to grant or revoke Owner/Admin roles. Consumes 1 paid seat. - **Admin**: Full system, service, schedule, and user management. Consumes 1 paid seat. - **User (On-call)**: Active incident responder. Can join rotations, receive alert pages, acknowledge/resolve incidents. Consumes 1 paid seat. - **Viewer**: Read-only observer. Can inspect incidents, services, and schedules. Cannot be paged or mutate state. **Unlimited and free** on all tiers; consumes 0 seats. ## Optional - [Full Documentation Corpus](https://oncallalert.dev/llms-full.txt): Complete documentation corpus in a single plain markdown document. - [Blog RSS Feed](https://oncallalert.dev/blog/feed.xml): RSS 2.0 feed of OnCallAlert blog posts, newest first. ## Pricing - [Pricing](https://oncallalert.dev/pricing): Flat plans by team size, not per seat. Core $699/year (15 on-call and admin users), Team $149/month or $1,499/year (50 users), Business $499/month or $4,999/year (200 users), Unlimited $999/month or $9,999/year. Viewers are free and unlimited on every plan. Every plan includes schedules, escalations, Slack, analytics, high-priority escalation, one public status page (free yourname.oncallalert.dev address), Ask AI (BYOK, local LLMs supported through Ollama), the MCP server and the Terraform provider. Team and up add the mobile app and dead-man's switch, and a custom status page domain as a $5/month add-on. Support: standard on Core and Team, priority on Business, 24/7 priority with onboarding on Unlimited. Feature requests: https://github.com/OnCallAlert/oncallalert/discussions