Set up agent notification channel

Agent notification channels let you trigger actions inside your infrastructure in response to events that happen in nullplatform. This allows you to build event-driven workflows that remain fully scoped within your own environment.

Example use cases

• Run a script when a service is updated
• Notify your CI/CD system when a scope completes
• Trigger cleanup after a failure or timeout
• Chain additional scopes or actions based on event type

How it works

The diagram below shows the basic flow when a notification channel is triggered:

What happens step by step

1. A platform event (e.g. service deployed) is emitted by nullplatform.
2. A configured notification channel picks up the event.
3. If the event matches the channel’s tag selector, the agent is notified.
4. The agent executes the command you’ve configured (e.g. a local script).
5. Logs and results are optionally sent back to the platform for visibility.

Create a channel

Before you start

You’ll need a separate API key with the following roles:

• agent, developer, ops, secops and secrets-reader.
• Roles must be at the account level level or the setup won’t work.

Set it up

From the UI:

1. Go to Platform settings > Channels and click + New channel.
2. Set the source (e.g Service).
3. Select Agent as the type.
4. Fill in configuration, then click Create channel.

From the CLI or API:
If you want to use any of this tools instead, see our API reference for details and request examples.

Example: Trigger a script (type: exec)

This example runs a shell script when a service event matches the specified tags:

{
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "source": ["service"],
  "type": "agent",
  "configuration": {
    "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",
    "command": {
      "type": "exec",
      "data": {
        "cmdline": "entrypoint.sh --service-path=\"$SERVICE_PATH\"",
        "environment": {
          "NP_ACTION_CONTEXT": "${NOTIFICATION_CONTEXT}"
        }
      }
    },
    "selector": {
      "environment": "local"
    }
  },
  "filters": {
    "service.specification.slug": "$service-spec-slug"
  }
}