alphorn

KO | EN

gitlite — search

#ruby #agents #bash #framework #mcp #go #vue #pytorch #shell #claude-code

(★ 9)

Self-hostable, open-source notification router. Receives webhooks and routes messages to 20+ channels (Slack, Discord, Email, Telegram, etc.) with filtering rules, retries, and real-time SSE streaming.

File Explorer

ZIP Download

- - docker.yml
- brand.md
- - migration_lock.toml
- schema.prisma
- logo.svg
- og-image.png
- - apple-icon.png
  - error.tsx
  - global-error.tsx
  - globals.css
  - icon.png
  - layout.tsx
  - not-found.tsx
- - discord.meta.ts
  - discord.ts
  - errors.ts
  - fetch.ts
  - google-chat.meta.ts
  - google-chat.ts
  - gotify.meta.ts
  - gotify.ts
  - index.ts
  - mailgun.meta.ts
  - mailgun.ts
  - matrix.meta.ts
  - matrix.ts
  - mattermost.meta.ts
  - mattermost.ts
  - meta-types.ts
  - meta.ts
  - ntfy.meta.ts
  - ntfy.ts
  - opsgenie.meta.ts
  - opsgenie.ts
  - pagerduty.meta.ts
  - pagerduty.ts
  - pushover.meta.ts
  - pushover.ts
  - registry.ts
  - rocketchat.meta.ts
  - rocketchat.ts
  - sendgrid.meta.ts
  - sendgrid.ts
  - slack.meta.ts
  - slack.ts
  - smtp.meta.ts
  - smtp.ts
  - sse.meta.ts
  - sse.ts
  - subject.ts
  - teams.meta.ts
  - teams.ts
  - telegram.meta.ts
  - telegram.ts
  - test-notification.ts
  - twilio-sms.meta.ts
  - twilio-sms.ts
  - types.ts
  - utils.ts
  - vonage-sms.meta.ts
  - vonage-sms.ts
  - webhook-url-field.ts
  - webhook.meta.ts
  - webhook.ts
  - zulip.meta.ts
  - zulip.ts
- - app-sidebar.tsx
  - breadcrumbs.tsx
  - channel-config-form.tsx
  - channel-icons.tsx
  - channel-selector.tsx
  - confirm-dialog.tsx
  - expandable-error.tsx
  - filter-builder.tsx
  - filter-test-panel.tsx
  - org-switcher.tsx
  - status-badge.tsx
  - theme-provider.tsx
  - theme-toggle.tsx
  - webhook-host-hint.tsx
- - use-mobile.ts
- - api-key.ts
  - db.ts
  - delivery.ts
  - format-date.ts
  - is-hosted.ts
  - logger.ts
  - org-slug.ts
  - queue.ts
  - rate-limit.ts
  - safe-path.ts
  - slack-compat.ts
  - toast-error.ts
  - utils.ts
  - version.ts
  - webhook-cache.ts
- - index.ts
- - deliver.ts
  - failure-notifier.ts
  - index.ts
  - retention.ts
  - standalone.ts
  - sweep.ts
- instrumentation-client.ts
- instrumentation.node.ts
- instrumentation.ts
- proxy.ts
- - auth.test.ts
  - health.test.ts
  - sse-stream.test.ts
  - webhook.test.ts
- - api-key.test.ts
  - channel-registry.test.ts
  - email-templates.test.ts
  - filter-schema.test.ts
  - filter.test.ts
  - logger.test.ts
  - queue.test.ts
  - slack-compat.test.ts
  - sse-connection-registry.test.ts
  - sse-format.test.ts
  - subscription-events.test.ts
  - telegram.test.ts
  - utils.test.ts
  - webhook-cache.test.ts
  - webhook-channel-schema.test.ts
  - webhook-extract-heuristic.test.ts
  - webhook-extract-template.test.ts
  - webhook-extract.test.ts
  - webhook-loop-hops.test.ts
  - webhook-loop-same-host.test.ts
  - worker-deliver.test.ts
  - worker-failure-notifier.test.ts
  - worker-sweep.test.ts
.dockerignore
.env.example
.gitignore
AGENTS.md
CLAUDE.md
components.json
CONTRIBUTING.md
docker-compose.yml
docker-entrypoint.sh
Dockerfile
eslint.config.mjs
LICENSE
next.config.ts
NOTICE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
postcss.config.mjs
prisma.config.ts
README.md
SECURITY.md
TRADEMARK.md
tsconfig.json
vitest.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Self-hostable notification router for developers and ops teams.**

Receive webhooks, route messages to 20+ channels, filter with a powerful rule DSL.

[![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL--3.0--or--later-teal.svg)](https://raw.githubusercontent.com/alphorn-dev/alphorn/main/LICENSE)
[![Next.js 16](https://img.shields.io/badge/Next.js-16-black.svg)](https://nextjs.org)
[![PostgreSQL 18](https://img.shields.io/badge/PostgreSQL-18-336791.svg)](https://www.postgresql.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6.svg)](https://www.typescriptlang.org)

</div>

---

Alphorn is an open source notification router. Point any service that can send a webhook at Alphorn, and it will fan the message out to Slack, Discord, Telegram, Email, PagerDuty, Opsgenie, and multiple other destinations — with filtering, retries, rate limits, and delivery history built in.

Think of it as a self-hosted alternative to commercial notification hubs, built on a boring, scalable stack (PostgreSQL + Next.js + pg-boss) that you can run yourself.

## Features

- **20+ delivery channels** — Slack, Discord, Microsoft Teams, Telegram, Mattermost, Rocket.Chat, Google Chat, Zulip, Matrix, ntfy, Gotify, Pushover, PagerDuty, Opsgenie, Twilio SMS, Vonage SMS, SMTP, SendGrid, Mailgun, generic Webhook, SSE, and more.
- **Powerful filter DSL** — route messages by priority, tags, title, body, or payload fields. Regex supported (safely).
- **Reliable delivery** — pg-boss queue with retries (5 attempts, exponential backoff), permanent vs. transient error handling, 7-day job retention.
- **Real-time streaming** — SSE endpoint for live event feeds. Dedicated SSE server for horizontally scaled deployments.
- **Multi-tenant** — Better Auth with organizations, invitations, roles, and two-factor (TOTP).
- **Optional billing** — Paddle integration with plan gating if you want to run Alphorn as a service.
- **Horizontally scalable** — stateless web, standalone workers, shared Postgres + S3-compatible storage. No local state.
- **Observable** — structured Pino logs and Sentry integration out of the box.
- **Self-hostable first** — one `docker compose up` away. No cloud lock-in, no mandatory external services.

## Quick start

### Docker Compose (recommended)

```bash
git clone https://github.com/alphorn-dev/alphorn.git
cd alphorn
cp .env.example .env
# edit .env — at minimum set BETTER_AUTH_SECRET
docker compose up -d
```

Open <http://localhost:3000> and create your first account.

### Local development

Requirements: Node.js 20.9+, pnpm, PostgreSQL 18.

```bash
pnpm install
cp .env.example .env
pnpm db:deploy
pnpm dev
```

optional: you can run one or multiple workers via:

```bash
pnpm dev:worker

# or build and run worker with defined concurrency
# pnpm build:worker && WORKER_CONCURRENCY=50 node --env-file=.env worker.mjs
```

## Architecture

```
┌────────────┐       ┌──────────────┐       ┌────────────────┐
│  Webhook   │─────▶│   Alphorn    │─────▶│  pg-boss queue │
│  producer  │       │ (Next.js 16) │       │  (PostgreSQL)  │
└────────────┘       └──────────────┘       └────────┬───────┘
                                                     │
                                             ┌───────▼────────┐
                                             │ Delivery worker│
                                             └───────┬────────┘
                                                     │
                ┌────────────┬────────────┬──────────┼──────────┬────────────┐
                ▼            ▼            ▼          ▼          ▼            ▼
             Slack       Discord      Telegram    Email    PagerDuty    ... 19 more
```

- **`src/proxy.ts`** — auth routing.
- **`src/channels/`** — plugin registry. Each channel is a `ChannelHandler` with a Zod config schema and `send()` method.
- **`src/worker/`** — pg-boss-backed delivery worker. Runs embedded (`MODE=all`) or standalone (`MODE=worker`).
- **`src/lib/filter/`** — Zod discriminated-union filter DSL with safe regex.
- **`src/lib/sse/`** — in-memory SSE registry. For multi-instance deployments, use the standalone `pnpm sse-server`.

See [`AGENTS.md`](./AGENTS.md) for the full architecture and conventions reference.

## Runtime modes

`MODE` environment variable controls what each process runs:

| Mode            | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `all` (default) | Web server + embedded worker. Good for single-instance deployments.      |
| `web`           | Web server only. Use when running workers separately.                    |
| `worker`        | Standalone delivery worker. Scale horizontally behind a shared Postgres. |

For horizontally scaled SSE, run `pnpm sse-server` with `SSE_MODE=standalone` and a shared `SSE_INTERNAL_SECRET`.

## Configuration

All configuration is via environment variables. Copy `.env.example` to `.env` — it is the source of truth and documents every option, including optional integrations (OAuth, SMTP, Sentry, S3).

**Minimum required:**

| Variable             | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `DATABASE_URL`       | PostgreSQL connection string                            |
| `BETTER_AUTH_SECRET` | Random secret — generate with `openssl rand -base64 32` |
| `BETTER_AUTH_URL`    | Public URL of your instance                             |

## Testing

```bash
pnpm test             # all tests
pnpm test:unit        # pure logic
pnpm test:integration # hits a real Postgres
```

Unit tests cover the filter DSL, billing math, and channel config parsing. Integration tests exercise Prisma, pg-boss, and route handlers against a real database.

## Contributing

Contributions are welcome. Before opening a PR:

1. Read [`AGENTS.md`](./AGENTS.md) — it documents the stack, conventions, and design principles.
2. Run `pnpm lint` and `pnpm test`.
3. Keep changes focused; new business logic (channels, filters, billing, routing) should come with tests.

For new channels, implement the `ChannelHandler` interface in `src/channels/` and register it in `registry.ts`. Throw on failure so pg-boss can retry — distinguish permanent vs. transient errors.

## License

Alphorn is **dual-licensed**: free under
[AGPL-3.0-or-later](./LICENSE) for the community, and available under a
commercial license for companies that cannot comply with AGPL terms.

**AGPL-3.0-or-later (free):**

- Self-host Alphorn for free — personal, internal business, non-profit,
  or commercial use.
- Read, modify, and redistribute the source code.
- If you run a modified version as a network service, you must publish
  your modifications under AGPL-3.0-or-later.
- AGPL-3.0 is [OSI-approved open source](https://opensource.org/license/agpl-v3).

**Commercial license (paid):**

If your organization cannot accept AGPL terms — for example, you need to
integrate Alphorn into a proprietary product or your legal policy prohibits
AGPL — a commercial license is available. Contact
<hello@alphorn.dev>.

The AGPL and commercial licenses cover copyright in the source code. They
do not grant rights to use the Alphorn name, logo, or confusingly similar
branding for unofficial products or hosted services. See
[`NOTICE`](./NOTICE) for the project license notice,
[`TRADEMARK.md`](./TRADEMARK.md) for the trademark policy, and
[`CONTRIBUTING.md`](./CONTRIBUTING.md) for contributor license terms.

alphorn

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README