Skip to main content

Set up your override environment

Before you can start overriding scopes, you’ll need to set up a few things to make sure nullplatform can find and execute your custom logic.

This setup is required whether you're applying configuration tweaks or fully replacing workflows.

1. Choose a base scope to extend​

You'll need a base scope as a starting point. This guide assumes you're extending our prod-ready Kubernetes scope, but overrides work with any agent-backed scope.

💡 You won’t modify this repo directly—instead, you’ll reference it from your own override repo.

2. Prepare your override repo​

Create a Git repository where you’ll store your:

  • values.yaml file (for config overrides)
  • Custom workflows or scripts (for behavior overrides)

Your repo might look like:

your-override-repo/
├── values.yaml
├── scope/workflows/
│ ├── create.yaml
│ └── delete.yaml
├── deployment/workflows/
│ └── initial.yaml
└── ...

3. Create an API key​

  1. In the platform UI, go to Platform settings > API keys, and click + New API key.
  2. Select the account resource where the API key's roles will be assigned.

⚠️ Important: Roles must be assigned at the account level or the setup won’t work.

  1. Select the required roles: agent, developer, ops, and secops.
  2. Save your API key somewhere safe—you'll need it in the next steps.

4. Set up the notification channel​

The notification channel tells the agent where to find your override logic and when to run it.

You can create it via the UI: Go to Platform settings > Channels, and click + New channel.

You’ll need to specify:

  • the base scope path,
  • your override path, and
  • the context used during execution.

Here’s an example of a notification channel configured for an override:

{
  "configuration": {
    "api_key": "AAAA.1234567890abcdef1234567890abcdefPTs=",
    "command": {
      "data": {
        "cmdline": "/root/.np/nullplatform/scopes/entrypoint --service-path=/root/.np/nullplatform/scopes/k8s --overrides-path=/root/.np/your-org/your-override-repo",
        "environment": {
          "NP_ACTION_CONTEXT": "'${NOTIFICATION_CONTEXT}'"
        }
      },
      "type": "exec"
    },
    "selector": {}
  },
  "filters": {
    "service.specification.slug": "your-service-spec"
  },
  "nrn": "organization=1:account=2:namespace=3:application=4",
  "source": [
    "telemetry",
    "service"
  ],
  "status": "active",
  "type": "agent"
}

Note: In the cmdline value, replace all example paths with the actual paths for your GitHub organization and repository.

For example, update /root/.np/your-org/your-override-repo to match your own override repository path.

5. Install (or update) the agent​

Your agent needs to know where your override code lives.

Set these environment variables:

export NP_API_KEY=<your_api_key>
export AGENT_TAGS="environment:development"
export AGENT_REPO="https://git-provider/your-org/your-override-repo.git#main,https://github.com/nullplatform/scopes.git#main"

Then install (or upgrade) the agent using Helm.

  • If the agent isn’t already installed:

    helm install nullplatform-agent nullplatform/nullplatform-agent \
    --set configuration.values.NP_API_KEY=$NP_API_KEY \
    --set configuration.values.TAGS="$AGENT_TAGS" \
    --set configuration.values.AGENT_REPO=$AGENT_REPO

  • If the agent is already running:

    helm upgrade nullplatform-agent nullplatform/nullplatform-agent \
    --set configuration.values.NP_API_KEY=$NP_API_KEY \
    --set configuration.values.TAGS="$AGENT_TAGS" \
    --set configuration.values.AGENT_REPO=$AGENT_REPO

You'll get a response like this to confirm the agent is up and running.

{"level":"info","time":"2025-08-05T16:40:56.721Z","message":"Commands Executor connected"}

For more info on the nullplatform agent, check our Agent docs.

You’re ready to override scopes​

Once your agent is running and the channel is configured, your custom logic will be picked up and applied during scope execution.

From here, you can: