Skip to main content

Run an agent‑backed scope locally

🎯 Goal: Set up your local environment and run a nullplatform agent‑backed scope using Docker and Minikube.

Introduction​

This guide helps you set up your local machine to work with nullplatform. You’ll create a demo release, configure a scope, spin up a local Kubernetes cluster, deploy the agent, and verify everything with simple checks.

This tutorial relies on the files in the Local setup scope repository.

What you’ll set up​

By the end of this guide, you'll have:

  • A local Kubernetes cluster (Minikube)
  • A nullplatform agent running locally
  • An example scope configured and registered
  • A demo release and a scope instance created from the UI

Prerequisites​

  • The nullplatform CLI: curl https://cli.nullplatform.com/install.sh | sh
  • Docker: brew install --cask docker
  • Gomplate: brew install gomplate
  • Minikube: brew install minikube
  • An API key at the account level with roles: agent, developer, ops, secops, secrets-reader, and ci

1. Create a new application (recommended)​

We recommend using a fresh application to avoid conflicts with existing scopes or configuration.

  1. In the platform UI, go to your home dashboard and click + Create application.
  2. Fill in the details and Create application.

2. Clone the scopes repository​

Open a terminal and clone the repository:

git clone https://github.com/nullplatform/examples-custom-scope-workshop.git
cd examples-custom-scope-workshop

This repo includes:

  • A base Kubernetes scope
  • Utility scripts for configuration and cluster setup
  • The agent deployment flow
scopes/
├── k8s/                        # Kubernetes-specific implementation
│   ├── scope/                  # Scope lifecycle actions
│   │   └── workflows/
│   │       ├── create.yaml
│   │       ├── update.yaml
│   │       └── delete.yaml
│   ├── deployment/             # Deployment actions
│   │   └── workflows/
│   │       ├── initial.yaml
│   │       ├── blue_green.yaml
│   │       └── ...
│   └── ...
└── create_asset                  # Create asset script
├── agent/                      # Agent deployment scripts
├── configure                   # Configuration script
└── entrypoint                  # Main execution script

3. Set the environment variables​

Configure your local environment:

export NP_API_KEY=<your_api_key_here>
export NRN=<your_application_nrn>
export SERVICE_PATH=k8s
  • NP_API_KEY — API key you created at the beginning of this tutorial.
  • NRN — Your application NRN you (You can retrieve it from the UI)
  • SERVICE_PATH — Path to the scope implementation in the repo (use k8s for this guide)

5. Create a release asset​

In the root of the repo, run:

./create_asset

This creates a release using a public Docker image defined in the repo.

✅ Checkpoint — Release created​

In the UI, open your application and go to Development > Releases. You should see a release named scope demo.

6. Configure the scope​

Time to set up the core components of your scope. Run the command:

./configure

The configuration script:

  • Registers the JSON schema that defines the scope’s parameters.
  • Creates action specs, like create-scope, delete-scope.
  • Sets up a notification channel so your agent can receive events.

7. Set up your local Kubernetes cluster​

Provision a local cluster to run the agent and supporting components (Minikube):

./agent/setup_minikube --enable-mount
./agent/configure_cluster

This creates the required Kubernetes namespaces and resources: nullplatform and nullplatform-tools.

8. Deploy the nullplatform agent​

Deploy the agent locally:

./agent/deploy_agent

From the menu:

  1. Choose option 1 to deploy the agent.
  2. Choose option 3 to tail the logs.

You should eventually see:

{"level":"info","message":"Commands Executor connected"}

9. Create and validate a scope​

Create a new scope from the UI:

  1. Go to your application and open Scopes.
  2. Click + New scope.
  3. Choose your new scope (look under target, default name: Containers-<your-username>).
  4. Fill in the config and Create scope.

Validate locally via port‑forward and health checks:

SERVICE=$(kubectl get service -n nullplatform -o json | jq -r '.items[0].metadata.name // empty')
kubectl port-forward service/"$SERVICE" 8080:8080 -n nullplatform
curl http://localhost:8080/health

Expected response:

{"status":"ok"}

(Optional) Test an example route:

curl http://localhost:8080/api/users

10. Clean up your environment​

  1. Delete scopes created for the guide (UI → application → Scopes).

  2. Shut down the agent:

    ./agent/deploy_agent    # Option 2: shut down, then Option 5: exit

  3. Stop Minikube:

    minikube stop

  4. (Optional) Delete the application you created for the guide.

Wrap‑up 🎉​

You now have a complete local development workflow for agent‑backed scopes:

  • Configured scopes and created a demo release
  • Deployed a local agent on Minikube
  • Validated the service via health checks

Troubleshooting​

Agent image not found (Minikube)

If your local Docker image isn’t available in the cluster:

eval "$(minikube docker-env)"
docker build -t agent-local:latest .

If that doesn’t work:

minikube stop && minikube delete
minikube start --dns-proxy=false --dns-domain="cluster.local"
Error: ErrImageNeverPull

If your agent pod logs show ErrImageNeverPull, your Kubernetes runtime cannot access your local Docker image.

Fix: make the image available to the cluster, then rebuild and redeploy:

eval "$(minikube docker-env)"
docker build -t agent-local:latest .
Agent log tail shows no activity

If your agent is deployed but not reacting to events:

  1. Verify your application NRN is correct.
  2. Confirm NP_API_KEY includes the required roles and was assigned at the account level.
  3. Manually trigger a scope action and tail logs:
./agent/deploy_agent  # Option 3: Tail logs

Related docs​