Going to Production

Agents built with Novu can run on your local machine. Deploy them to development and production environments when you are ready.

Local
Development
Production

By default, the agent runs on your local machine. To run the agent locally:

Scaffold your agent with npx novu init -t agent.
Add valid NOVU_SECRET_KEY and NOVU_API_URL values to your .env file.
Run the scaffolded project on your local machine.
Set the bridge option to Local in the agent overview section.

When you complete these steps, run the agent using the Novu CLI command below.

npx novu@latest dev --port <bridge_application_port> --no-studio

bridge_application_port - Port where your scaffolded project runs. Defaults to 4000.
no-studio - Disables Studio.

After you run the command, a tunnel starts on your machine. It forwards requests to your scaffolded project on bridge_application_port.Novu sets the bridge URL automatically to tunnel-url/api/novu.The agent listens for new messages and responds while running locally.

After you test the agent locally, deploy it to a development environment. A scaffolded app from npx novu init -t agent uses Next.js and exposes a /api/novu endpoint for communicating with Novu. Deploy the app to your preferred hosting provider, then copy the deployed URL.

Add valid NOVU_SECRET_KEY and NOVU_API_URL values in the environment variables section of your hosting provider.
Toggle the bridge option to Development in the agent overview section.
For a deployed app at https://dev.my-agent-app.com, use https://dev.my-agent-app.com/api/novu as the bridge URL in the agent overview section.

Before you use an agent in production, publish the agent from the development environment to the production environment. Use the Publish changes option on the dashboard.After you publish:

Publishing sends the agent to production with the same name, identifier, and description.
The agent stays inactive until you activate it from the agent overview section.
Configure and connect every provider again in the production environment.
Deploy the agent bridge application to the production environment.
Add valid NOVU_SECRET_KEY and NOVU_API_URL values in the environment variables section of your hosting provider.

Deploying to production

After you publish the agent and complete the above steps, deploy the agent bridge application to the production environment.

npx novu@latest sync --bridge-url <bridge_url> --secret-key <NOVU_SECRET_KEY> --api-url <NOVU_API_URL>

name: Deploy agent to Novu Cloud

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # https://github.com/novuhq/actions-novu-sync
      - name: Deploy agent to Novu Cloud
        uses: novuhq/actions-novu-sync@v2
        with:
          # The secret key used to authenticate with Novu Cloud
          # To get the secret key, go to https://web.novu.co/api-keys.
          # Required.
          secret-key: ${{ secrets.NOVU_SECRET_KEY }}

          # The publicly available endpoint hosting the bridge application
          # where notification entities (e.g. workflows, topics) are defined.
          # Required.
          bridge-url: ${{ secrets.NOVU_BRIDGE_URL }}

          # The Novu Cloud API URL to sync with.
          # Optional.
          # Defaults to https://api.novu.co
          api-url: https://api.novu.co

For example, with https://prod.my-agent-app.com as the bridge app URL, use https://prod.my-agent-app.com/api/novu as the bridge URL.In the CLI command above:

<bridge_url>: URL of your deployed agent bridge application.
<NOVU_SECRET_KEY>: secret key for your Novu account.
<NOVU_API_URL>: API URL for your Novu account.

You can also use our built-in GitHub Action to deploy your agent to the production environment. See Deploy with GitHub Actions for setup details.After you run the command, the agent overview section shows the updated production bridge URL.You can also set the bridge URL programmatically with Update an agent bridge.

Local tunnel bridge URLs cannot be activated on production environments (returns 403 Forbidden) to prevent accidental routing of production traffic to a local machine.

Going to Production

Deploying to production

Next steps

Conversation observability

Update an agent bridge API

​Deploying to production

​Next steps

Conversation observability

Update an agent bridge API

Deploying to production

Next steps