Alarum

Alarum documentation

Alarum is a centralised hub for all the events your stack fires: CI runs, cron jobs, deployments, errors, anything that can POST JSON. This guide walks through the concepts and day-to-day usage. For the developer-facing API reference, head to the Integration guide.

Quick start

From zero to first event in five steps:

  1. Sign in with GitHub or Codeberg from the login page.
  2. A default workspace is created automatically. Open Workspaces to add a project.
  3. Inside the project, open Settings → Tokens and create a token for your source (e.g. "GitHub Actions prod").
  4. Copy the token immediately, it's shown only once.
  5. POST your first event: 
    curl -X POST 'https://alarum.me/h' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"level":"success","title":"Hello from my script"}'

The event appears in your Inbox within seconds, and a push notification fires if you've granted permission. Need to integrate from a script, a CI pipeline, or an AI agent? The Integration guide has the full spec and copy-pasteable snippets for every common language.

Or pick yours straight from this dropdown: 

curl -X POST 'https://alarum.me/h' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"level":"success","title":"Deploy succeeded","message":"v1.2.3 shipped to production","source":"github-actions"}'

Workspaces & projects

Alarum organises everything in a two-level hierarchy:

  • Workspace, a group, typically representing a team, a company, or simply your personal stuff. Workspaces can be shared with other users via invitation. Each workspace has an owner and members.
  • Project, a topic within a workspace. One project per app or service is a good rule of thumb (e.g. "my-api", "backups", "monitoring"). Each project carries its own tokens, forwarders and notification rules.

To share a workspace, open it and use the invite action. Invitees receive a link they accept after signing in. They become full members and can read every event in every project of the workspace.

Tokens

Tokens are the ingestion credentials. One token grants permission to POST events to one project's URL, that's all. They look like alrm_….

  • One token per source. Create a distinct token for each CI workflow, cron job or service, so you can revoke just the one that leaks.
  • Shown only once. The full token is revealed on creation and never again, only a prefix/suffix is stored. Lost? Revoke and create a new one.
  • Revocation is instant. Sources using a revoked token start receiving HTTP 401 immediately.
  • Per-token configuration. Each token has its own row in the project Settings, with a Configure button to override notification rules for that source specifically (more in Notifications below).

Events & levels

An event is a single notification posted to a token. It has a level that drives how prominently it shows up and whether you receive a push for it. Picking the right level matters more than picking a long title.

infoRoutine, informational events. No push by default to avoid noise.Push: OFF
successSomething finished successfully, a deploy, a backup, a CI run.Push: ON
warnNeeds attention but the system is still working.Push: ON
errorSomething failed, a job, a job step, a check.Push: ON
criticalUrgent failure. Can override your quiet hours.Push: ON*

* critical can bypass your quiet hours when the "critical overrides quiet hours" toggle is on (default).

Beyond the level, an event carries a title (required), an optional message, source, tags, URL, fields, timestamp, color and author. The full payload schema is documented in the Integration guide.

Inbox & filters

The Inbox aggregates every event across every workspace you can see. Open a workspace or a project from the sidebar to scope the view down. New events arrive automatically, the page refreshes in the background without a visible flash, and a status dot on the Inbox icon turns yellow while a sync is in flight.

  • Filters, open the Filters drawer at the top of the inbox to narrow by level, tag, time range, or read state. Filters compose: pick multiple levels, multiple tags, etc.
  • Per-event actions, click an event to open its detail page. From there: mark as read/unread, delete (or restore a deleted event). Deleted events are hidden by default but can be revealed via the Show deleted toggle.
  • Bulk actions, use the Mark all as… dropdown to act on the entire current scope (global, current workspace, or current project).
  • Search, the search icon in the header opens a full-text search over title and message fields.

Notifications & quiet hours

Push notifications are per-device and per-user. Grant permission once in your browser; Alarum remembers it via a service worker. The same account on multiple devices receives push on every device that has subscribed.

Two layers of configuration decide whether a given event triggers a push for you:

  • Project defaults, open a project's Settings; the My notifications for this project block has one toggle per level. This applies to every event in that project unless a per-token override exists.
  • Per-token override, for a noisier source, open the project's token list, click Configure on the relevant token, and switch on Override project defaults. The toggles you set apply only to events coming in through that one token.

Quiet hours mute push notifications during a time window. They're configured globally per user (Settings → Notifications) and can be overridden project-by-project. critical events can optionally bypass quiet hours via a per-quiet-hours toggle.

Re-forwarding to Discord, Slack, or anywhere

A forwarder is an outgoing webhook that Alarum fires when an event arrives. Three types are supported:

  • Discord, point at a Discord channel webhook URL; events are formatted as Discord embeds with the matching colour for their level.
  • Slack, point at a Slack Incoming Webhook URL; events are formatted as Slack blocks.
  • Generic, any HTTPS endpoint. Provide an optional JSON template using variables ({{level}}, {{title}}, {{message}}, etc.) and the rendered body is POSTed.

Each forwarder has a minimum level filter, set it to error and you'll only get pinged on Slack for errors and criticals. It also has a trigger scope: either all events of the project, or only events that came in via one specific token. Use scoping to send your noisy "build started" pings to a low-priority channel while reserving the urgent channel for "build failed" from the same project.

When a forwarder POST succeeds, its row shows OK ago. On failure, the error message is captured and displayed inline so you can debug.

Reading your events outside the browser

Everything so far is about events coming in. Alarum can also be read from outside the app, so your events can live where you work: a panel in your terminal, a status line, a script that asks "did anything break?".

That needs a different kind of token. A project token only ever sends, which is why you can paste it into a CI job without a second thought. An agent token belongs to your account: it reads the events of every project you can reach and can mark them read, so it stays on your own machines. Create one under Settings → Your agent, where you also see when each was last used and can revoke a single machine. It is shown once. 

curl -H "Authorization: Bearer <agent token>" \
  'https://alarum.me/api/v1/events?level=error,critical&limit=20'

You can filter by project, workspace, level, tag, source or unread, page through with a cursor, and mark an event read from there, which clears it in the web inbox too. The full reference is in the integration guide. The agent API is part of the paid plans, and each token has a per-minute request allowance, which is ample for a panel refreshing every 30 seconds.

The Claude Code mod

If you work in Claude Code, the ready-made client is a mod: your events sit in a band above the prompt, or in a side pane, and a press drops one into the prompt box so a failing deploy becomes the next thing you ask about. Install it with: 

/plugin marketplace add FrBmt-BIGetNouf/alarum-claude-mod
/plugin install alarum@alarum

Then drop an agent token in an .alarum file at the root of the repository, and add that file to your .gitignore: 

token=alrm_at_…
api=https://alarum.me/api/v1

The band toasts on the levels you already set under each project's notification rules, so it says what you asked to be told, no more. It never lets the agent read .alarum, and masks any token a command happens to print. A repository without that file gets no band and makes no request at all.

Retention, account & security

Retention is tied to your plan, not to individual projects, and splits in two: a short detail history for the full raw events you can read, search and drill into from the Inbox (3 days on Discover, 30 days on Freelance, 90 days on Agency), and a much longer trend history made of lightweight daily rollups (event counts per project, day and level, plus the top tags and sources) that feeds the dashboard charts (1 month on Discover, 3 months on Freelance, 6 months on Agency). A daily cron deletes raw events older than your detail horizon, regardless of whether they were read; rollups keep your charts populated long after the raw data has aged out.

Sign-in identities. Your account can be linked to multiple OAuth providers (GitHub, Codeberg) so you can sign in with whichever is convenient. Open Settings → Profile to link or unlink a provider. Alarum will never let you unlink your last identity, that would lock you out.

Deleting your account is final. Settings → Danger zone lets you do it after typing your email to confirm. Workspaces you own, every project in them, all tokens, all forwarders and every push subscription on every device are removed in a single transaction.

More