1. Project Overview & Quickstart (novuhq/novu) Copy Chapter

File: README.md Copy Chapter

The open-source communication infrastructure for agents and products

Learn More »

Report a bug
·
Docs
·
Website
·
Join our Discord
·
Changelog
·
Roadmap
·
X
·
Contact us

Software is becoming more conversational, and user expectations are rising with it. People no longer want static, irrelevant notifications they glance at and forget, they want to engage, ask questions, and go deeper. Instead of a one-way report dropped in their inbox, they expect a thread they can explore: follow up on a metric, drill into an anomaly, or continue a conversation right where they left off. That shift, from broadcast to meaningful dialog is what Novu's communication infrastructure is built for.

⭐️ Why Novu? Copy Chapter

Every product and every agent eventually needs to talk to people, across the channels those people already use. Novu is the open-source layer that handles that communication for you, so you don't rebuild Inbox feeds, provider integrations, and channel webhooks from scratch every time.

There are two ways to build with Novu, and they share the same foundation: a single API and a unified conversation model.

• Communication infrastructure for products — Send notifications across Inbox/In-App, Email, SMS, Push, and Chat through one API, with workflows, digests, and an embeddable `` component.
• Agent Communication Infrastructure (ACI) — Connect any agent you've already built to any communication channel: Slack, Microsoft Teams, Telegram, WhatsApp, email through one conversation model.

🚀 Getting Started Copy Chapter

Create a free account and follow the instructions on the dashboard.

📚 Table of contents Copy Chapter

• Why Novu?
• Communication infrastructure for products
• Agent Communication Infrastructure (ACI)
• Getting Started
• Embeddable Inbox and Preferences
• Providers

📬 Communication infrastructure for products Copy Chapter

The notification platform that turns complex multi-channel delivery into a single component. Built for developers, designed for growth, powered by open source.

Novu provides a unified API to send notifications through multiple channels — Inbox/In-App, Push, Email, SMS, and Chat. Create custom workflows, define per-channel conditions, and let Novu deliver each notification in the most effective way, without stitching together a provider for every channel yourself.

• One API for all messaging providers
• Embeddable, real-time `` component
• Notification workflow engine with branching and conditions
• Digest engine to batch multiple notifications into a single message
• No-code email editor
• Embeddable preferences component so users control their own notifications

🤖 Agent Communication Infrastructure (ACI) Copy Chapter

You build the agent. Novu gives it a voice.

ACI is a complete suite for companies already building agents that need to talk to users on real communication channels. It connects your agent to any channel and abstracts away the quirks of each platform behind a single, unified conversation model.

Novu handles the plumbing in both directions: it receives inbound messages from each channel, normalizes them into one consistent shape, routes them to your agent, and sends your agent's responses back out, so you integrate once instead of building and maintaining a webhook handler per platform.

• Unified conversation model — one consistent model across every channel, instead of per-platform message formats and webhook quirks
• Bidirectional messaging — receive user messages and send agent replies through the same layer
• Channel integrations — Slack, Microsoft Teams, Telegram, WhatsApp, Email, and an In-App Inbox for agents
• Bring your own agent — works with whatever you've built, whether that's Claude Managed Agents, AI SDK, LangGraph, or a custom stack; Novu doesn't constrain your agent logic
• Best practices built in — conversation threading, reactions, channel-aware formatting, actions and a single integration surface
  Novu connects the agent to the world, it is not the agent itself.

Want to see ACI in action? Copy Section

We have built Novu Connect to showcase the power of ACI, build on integrate an existing Claude Managed Agent as a teammate in Slack, Telegram, or Email in less than 2 minutes.

Try it now:

npx novu@latest connect

Embeddable Inbox component Copy Chapter

Using the Novu API and admin panel, you can easily add a real-time notification center to your web app without building it yourself. You can use our React, or build your own via our API and SDK. React native, Vue, and Angular are coming soon.

Providers Copy Chapter

Novu provides a single API to manage providers across multiple channels with a simple-to-use API and UI interface.

Expand a channel below to browse supported providers.

💌 Email (20 providers)

📞 SMS (37 providers)

📱 Push (8 providers)

💬 Chat (13 providers)

📥 In-App (1 provider)

📋 Read Our Code Of Conduct Copy Chapter

Before you begin coding and collaborating, please read our Code of Conduct thoroughly to understand the standards (that you are required to adhere to) for community engagement. As part of our open-source community, we hold ourselves and other contributors to a high standard of communication. As a participant and contributor to this project, you agree to abide by our Code of Conduct.

💻 Need Help? Copy Chapter

We are more than happy to help you. If you are getting any errors or facing problems while working on this project, join our Discord server and ask for help. We are open to discussing anything related to the project.

🔗 Links Copy Chapter

• Home page
• Contribution guidelines
• Run Novu locally

🛡️ License Copy Chapter

Novu is a commercial open source company, which means some parts of this open source repository require a commercial license. The concept is called "Open Core," where the core technology is fully open source, licensed under MIT license, and the enterprise code is covered under a commercial license ("/enterprise" Enterprise Edition). Enterprise features are built by the core engineering team of Novu which is hired in full-time.

The following modules and folders are licensed under the enterprise license:

• enterprise folder at the root of the project and all of its subfolders and modules

💪 Thanks to all of our contributors Copy Chapter

Thanks a lot for spending your time helping Novu grow. Keep rocking 🥂

The beatiful header animation was contributed by LottieFiles ❤️

File: apps/worker/README.md Copy Chapter

Description Copy Chapter

Nest framework TypeScript starter repository.

Installation Copy Chapter

$ npm install

Running the app Copy Chapter

# development
$ npm run start

# watch mode
$ npm run start:dev

# incremental rebuild (webpack)
$ npm run webpack
$ npm run start:hmr

# production mode
$ npm run start:prod

Test Copy Chapter

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

Support Copy Chapter

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch Copy Chapter

• Author - Kamil Myśliwiec
• Website - https://nestjs.com
• X - @nestframework

License Copy Chapter

Nest is MIT licensed.

File: apps/widget/README.md Copy Chapter

Widget

How to run e2e test in local? Copy Chapter

Run npm run start:test script in the following apps on separate terminals:

1. apps/api
2. apps/ws
3. apps/widget

Once all the above scripts are running, run npm run cypress:open from apps/widget to view the Cypress Test Runner.

File: apps/web/README.md Copy Chapter

Getting Started with Create React App

This project was bootstrapped with Create React App.

Available Scripts Copy Chapter

In the project directory, you can run:

`yarn start` Copy Section

Runs the app in the development mode.
Open http://127.0.0.1:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

`yarn test` Copy Section

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

`yarn build` Copy Section

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

`yarn eject` Copy Section

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren't satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc.) right into your project, so you have full control over them. All the commands except eject will still work, but they will point to the copied scripts, so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However, we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Learn More Copy Chapter

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

File: apps/api/README.md Copy Chapter

@novu/api-service

A RESTful API for accessing the Novu platform, built using NestJS.

Running the API Copy Chapter

See the docs for Run in Local Machine to get setup. Then run:

# Run the API in watch mode
$ npm run start:api

Test Copy Chapter

Unit Tests Copy Section

# unit tests
$ npm run test

E2E tests Copy Section

See the docs for Running on Local Machine - API Tests.

Adding a new Endpoint Copy Chapter

Choose the right controller / new controller. Copy Section

• If the endpoint is related to an existing entity, add the endpoint to the existing controller.

Add the correct decorators to the controller method. Copy Section

• Use the @Get, @Post, @Put, @Delete decorators to define the HTTP method.
• Use the @Param, @Query, @Body decorators to define the parameters.
• Use the @RequireAuthentication() decorator to define the guards as well as make it accessible to novu web app.
• Use the @ExternalApiAccessible decorator to define the endpoint as accessible by external API (Users with Api-Key) & The official Novu SDK.

Naming conventions

• for the controller methods should be in the format getEntityName, createEntityName, updateEntityName, deleteEntityName.
• In Case of a getAll / List use the list prefix for the method name and don't forget to add pagination functionality.
  • Use the @SdkUsePagination decorator to alert the sdk of a paginated endpoint (will improve DX with an async iterator) the pagination parameters.
• In case of a uniuqe usecase outside of the basic REST operations, attempt to use the regular naming conventions just for a sub-resource.
  • @SdkGroupName - Use this decorator to group the endpoints in the SDK, use . separator to create a subresource (Ex' 'Subscribers.Notifications' getSubscriberNotifications), the original resource is defined as an openApi Tag .
  • @SdkMethodName in case of a unique operation, use this decorator to define the method name in the SDK.

OpenAPI (formerly Swagger) Copy Chapter

The Novu API utilizes the @nestjs/swagger package to generate up-to-date OpenAPI specifications.

A web interface to browse the published endpoints is available during local development at localhost:3000/openapi. An OpenAPI specification can be retrieved at api.novu.co/openapi.yaml.

To maintain consistency and quality of OpenAPI documentation, Novu uses Spectral to validate the OpenAPI specification and enforce style. The OpenAPI specification is run through a Github action on pull request, and call also be run locally after starting the API with:

$ npm run lint:openapi

The command will return warnings and errors that must be fixed before the Github action will pass. These fixes are created by making changes through the @nestjs/swagger decorators.

Migrations Copy Chapter

Database migrations are included for features that have a hard dependency on specific data being available on database entities. These migrations are run by both Novu Cloud and Novu Self-Hosted users to support new feature releases.

How to Run Copy Section

The npm run migration script is available in the package.json to ensure script changes are DRY and consistent. This script is included in user-facing communications such as our documentation and release notes, and the script naming therefore MUST remain stable.

The path to the migration to run is passed as a positional argument to the script. For example, to run the Add Integration Identifier script, we would enter the following:

npm run migration -- ./migrations/integration-scheme-update/add-integration-identifier-migration.ts

Conventions Copy Section

These migrations live in the ./migrations directory, and follow the naming convention of:
./migrations/<CHANGE_DESCRIPTION>/<CHANGE_ACTION>.ts. Each <CHANGE_DESCRIPTION> may have 1 or more <CHANGE_ACTION>.ts scripts. For example:

.
└── migrations/
    └── integration-scheme-update/
        ├── add-integration-identifier-migration.ts
        └── add-primary-priority-migration.ts

File: docker/enterprise/Readme.md Copy Chapter

Novu Enterprise Docker Compose

This documentation guides you through the process of setting up a non-production deployment of Novu Enterprise using Docker Compose.

You will need to contact sales to get a token.

Before You Begin Copy Chapter

Ensure that the following software has been installed on your system:

• Docker and docker-compose
• Git

Guide Copy Chapter

Get the Code Copy Section

Warning: Before you start this process, If you have an existing mongodb volume you will need to remove it to
ensure the enterprise tables are installed correctly.

Clone the Novu repository, navigate to this directory, and run the following command with the provided username and token

# Add the token to the shell env
NOVU_ENTERPRISE_TOKEN=ghp_xxxx

# Copy the example env file
cp .env.example .env

# Login
docker login ghcr.io --username  --password "$NOVU_ENTERPRISE_TOKEN"

# Start Novu
docker-compose -f ./docker-compose.enterprise.yml up

Now visit http://127.0.0.1:4200 to start using Novu.

Secure Your Setup Copy Chapter

Though we provide some example secrets for getting started, it's highly recommended NOT to deploy your Novu setup using the defaults provided.
Update the .env file with your own secrets, in particular, make sure you replace:
JWT_SECRET: A secret key used by the API to generate JWT tokens.

Redis Configuration Copy Chapter

You can configure Redis TLS by adding the following variables to the .env file and specifying the needed properties:
REDIS_TLS={"servername":"localhost"}
REDIS_CACHE_SERVICE_TLS={"servername":"localhost"}

Configuration Copy Chapter

For simplicity, we made decisions that might not be optimal for production:

• The database is on the same machine as the servers.
• The storage uses the filesystem backend instead of S3.

We strongly advise decoupling your storage before deploying Novu in a production environment.

File: docker/kubernetes/kustomize/README.md Copy Chapter

Kubernetes Deployment Files

Prerequisites Copy Chapter

To deploy these files, kustomize is required. You can also use a tool such as Argo CD which builds and deploys the files for you.

• Kustomize
• Argo CD

Build Copy Chapter

How to build:

kustomize build .

Deploy Copy Chapter

How to deploy:

kustomize build . | kubectl apply -f -

Convert Copy Chapter

These files have been generated with the following command, having the docker-compose.yaml in the directory:

kompose convert

Then, the following modifications have been made:

1. Add kustomize, include files, add config
2. Add env generator
3. Update env to match env generator
4. Add labels
5. Removed unnecessary code from kompose

File: docker/kubernetes/helm/README.md Copy Chapter

Novu Helm Chart

Novu provides a unified API that makes it simple to send notifications through multiple channels, including In-App, Push, Email, SMS, and Chat. With Novu, you can create custom workflows and define conditions for each channel, ensuring that your notifications are delivered in the most effective way possible.

Overview of Novu

TL;DR Copy Chapter

helm install my-novu ./ --set store.encryptionKey=$(openssl rand -base64 32)

Introduction Copy Chapter

This Helm chart is inspired by Bitnami charts and make use of Bitnami charts for its dependencies.

This chart bootstraps a Novu deployment on a Kubernetes cluster using the Helm package manager.

Prerequisites Copy Chapter

• Kubernetes 1.19+
• Helm 3.2.0+

Installing the Chart Copy Chapter

To install the chart with the release name my-novu:

helm install my-novu ./ --set store.encryptionKey=$(openssl rand -base64 32)

These commands deploy a Keycloak application on the Kubernetes cluster in the default configuration.

Tip: List all releases using helm list

Uninstalling the Chart Copy Chapter

To uninstall/delete the my-release deployment:

helm delete my-novu

The command removes all the Kubernetes components associated with the chart and deletes the release.

Parameters Copy Chapter

Global parameters Copy Section

Common parameters Copy Section

Novu API Parameters Copy Section

Novu Worker Parameters Copy Section

Novu Websocket Parameters Copy Section

Novu Web Parameters Copy Section

Persistence Parameters Copy Section

Secrets definition Copy Section

Mongodb configuration Copy Section

Redis configuration Copy Section

Localstack (S3) configuration Copy Section

External mongoDB database configuration Copy Section

External redis configuration Copy Section

External s3 configuration Copy Section

File: docker/local/Readme.md Copy Chapter

Running novu locally Copy Chapter

For a full guide on running novu locally for development needs, please read our guide here: https://docs.novu.co/community/run-in-local-machine

Advanced - Running with a Redis Cluster Copy Section

Novu has support for redis cluster, however you must set the following env variables to enable it:

// To be determined

In the local development example in the docker-compose.redis-cluster.yml file, the primary nodes are hard coded to 6391 through 6393 and
the secondary (read) node to 6394 through 6396 on localhost.
In addition, for the queue service there is a redis sentinel cluster that has ones primary and two read nodes
with append-only file enabled that run on ports 6381 through 6383 on localhost.
We have also set up redis commander on 5001 for you to be able to see the keys and statistics of the cluster.

File: docker/Readme.md Copy Chapter

Docker is the easiest way to get started with self-hosted Novu,
however if you want to set up the system on docker for local development look here
or if you want to deploy Novu to Kubernetes using Helm check here or using Kustomize check here.

Before you begin Copy Chapter

You need the following installed in your system:

• Docker and docker-compose
• Git

Quick Start Copy Chapter

Get the code Copy Section

Clone the Novu repo and enter the docker directory locally:

# Get the code
git clone https://github.com/novuhq/novu

# Go to the docker folder
cd novu/docker

# Copy the example env file
cp .env.example ./local/deployment/.env

# Start Novu
docker-compose -f ./local/deployment/docker-compose.yml up

Now visit http://127.0.0.1:4200 to start using Novu.

Securing your setup Copy Section

While we provide you with some example secrets for getting started, you should NEVER deploy your Novu setup using the defaults provided.

Update Secrets Copy Section

Update the .env file with your own secrets. In particular, these are required:

• JWT_SECRET: used by the API to generate JWT keys

Redis config Copy Section

Redis TLS can be configured by adding the following variables to the .env file and specifying the necessary properties inside:

• REDIS_TLS={"servername":"localhost"}
• REDIS_CACHE_SERVICE_TLS={"servername":"localhost"}

Configuration Copy Chapter

To keep the setup simple, we made some choices that may not be optimal for production:

• the database is in the same machine as the servers
• the storage uses the filesystem backend instead of S3

We strongly recommend that you decouple your database before deploying.

Next steps Copy Chapter

• Got a question? Ask here.

2. Official Technical Reference & Guides (novuhq/docs) Copy Chapter

The <Inbox /> infrastructure for modern products

Documentation

🚀 Quick Start Copy Chapter

Built with Fumadocs and pnpm.

Prerequisites: Node.js 22+, pnpm 11+, and Vale 3.9.1+ (only needed if you want to run prose linting locally; CI installs it automatically)

# Clone and setup
git clone https://github.com/YOUR_USERNAME/docs.git
cd docs
pnpm install
pnpm dev

Open http://localhost:3010 to view locally.

Scripts:

• pnpm dev - Development server
• pnpm build - Production build
• pnpm lint - Lint code
• pnpm lint:prose:sync - Download Vale style packages (run once after install)
• pnpm lint:prose - Run Vale prose linting against content/ (requires Vale on PATH)

🤝 Contributing Copy Chapter

1. Make Changes

   bash Copy

   git checkout -b feature/your-fix
   # Edit files
   pnpm dev  # Test locally
   git commit -m "docs: your changes"
   git push origin feature/your-fix

2. Create Pull Request

   • Go to GitHub repo
   • Click "New Pull Request"
   • Use descriptive title with docs:, fix:, or feat: prefix
   • Include screenshots for visual changes

Guidelines:

• Write clear, concise documentation

• Test code examples before submitting

• Follow existing file structure

• Is something missing in docs? create a new github issue

  Need Help? conatct us at [email protected] or join Discord.

Thank you for contributing! 🙏