Agent Deployment

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

Agent on your local machine

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.

Agent in development

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.

Agent in production

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.

Using Novu CLI

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

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 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.

After you run the command, the agent overview section shows the updated production bridge URL.

Using GitHub Actions

You can use our built-in GitHub Action to deploy your agent to the production environment.-->

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