NetStacksNetStacks
Contact SalesDownload

Plugin System

Enterprise

Install, enable, disable and remove NetStacks Controller plugins from the admin console, and see where plugin screens appear in the admin console and the Terminal.

Overview

Plugins add features to the NetStacks Controller. Each plugin is a small service packaged as a .nspkg file. When you upload it, the Controller builds the plugin's Docker image, creates a database schema for it, and lists it on the Plugins page. When you enable it, the Controller starts the plugin's container and routes requests to it under /api/plugins/<name>/.

NetStacks provides two plugins for network operations:

PluginNameWhat it does
Alert Ingestion & PipelinealertsReceives alerts over HTTP, de-duplicates them, routes them with pipeline rules, hands them to AI agents for triage, and escalates through notification channels. See Alerts.
Incidents & ITSMincidentsTracks incidents with linked alerts and comments, can create incidents automatically after AI triage, and syncs with ServiceNow, Jira or a generic webhook. See Incidents & ITSM.

You can also build your own plugin. See Building Plugins.

Controller only
Plugins run on the NetStacks Controller. The Terminal shows plugin panels only when it is connected to a Controller (enterprise mode). The standalone Terminal has no plugins.

Requirements

  • Docker on the Controller host. The Controller runs each plugin as a Docker container named netstacks-plugin-<name> on the Controller's Docker network. If Docker isn't available, the plugin pages show “Plugin system requires Docker — ensure Docker is running and restart the controller”.
  • Permissions. You need access to Administration to open the Plugins page, and the system.manage permission to upload, enable, disable, configure or uninstall plugins. See Roles & Permissions.
  • The plugin package. A .nspkg file of up to 100 MB.

The Plugins Page

In the admin console, open Administration and, under System, click Plugins (route /admin/plugins). The page lists every installed plugin for your organization and refreshes itself every 15 seconds.

Plugins page in the admin console listing Alert Ingestion & Pipeline 1.0.1 and Incidents & ITSM 1.0.0, both enabled, with Disable and Uninstall actions

The table has these columns:

ColumnDescription
NameThe plugin's display name. Click it to open the plugin detail page.
VersionThe version from the plugin's manifest.
DescriptionA short description from the manifest.
Stateenabled, disabled or error.
ActionsEnable or Disable, and Uninstall.

Install a Plugin

  1. On the Plugins page, click Upload Plugin. The Upload Plugin Package card opens.
  2. Drag your .nspkg file onto Drop .nspkg file here, or click the area to browse for it.
  3. Wait while “Uploading plugin...” is shown. The Controller checks the package and its manifest, builds the plugin's Docker image, creates the plugin's database schema and runs its migrations.
  4. The plugin appears in the table in the disabled state. It isn't running yet — enable it to start it.
Upload Plugin Package card with the Drop .nspkg file here drop zone above the installed plugins table
Upload errors
  • “Invalid file type. Please upload a .nspkg file.” — only files ending in .nspkg are accepted.
  • A conflict error means a plugin with the same name is already installed in your organization. To replace it, follow Update a Plugin.
  • Manifest errors list the field that failed validation (for example a missing port or an invalid version). See the manifest reference.
Install only plugins you trust
A plugin runs as a service next to the Controller and receives access to the platform capabilities its manifest requests. Review the Required Capabilities on the plugin detail page before you enable it.

Enable or Disable a Plugin

Enable

Click Enable in the plugin's row (or on its detail page). The Controller applies any pending migrations, starts the plugin container and, once it is running, sets the state to enabled. The plugin's panels then appear in the admin console sidebar and in the Terminal.

If the container can't start, the state changes to error and the detail page shows the reason (“Failed to start: …”).

Disable

Click Disable. The Controller stops the plugin's container and sets the state to disabled. The plugin's data stays in its database schema, and its panels disappear from the sidebar and the Terminal. Enable it again to resume.

Restarting a plugin
To restart a plugin, click Disable and then Enable.

When the Controller starts, it restarts the containers of all plugins that are in the enabled state. If a container is missing (for example after restoring the Controller database on a new host), the Controller rebuilds it from the stored package.

Plugin Details and Health

Click a plugin's name to open its detail page (/admin/plugins/<name>). It has Enable/Disable and Uninstall buttons and these cards:

  • Plugin Information — Name, Version, Docker Image, Port, Description, Required Capabilities, Created and Updated.
  • Health Status (enabled plugins only) — Container Status, Health Status, Running and Container ID. If the container's health check is failing you see “Warning: Plugin container is not healthy”.
  • Settings — a form generated from the plugin's settings schema, if it has one. Plugins without a schema show “This plugin has no configurable settings.”
Plugin detail page for Alert Ingestion & Pipeline showing Plugin Information (name alerts, image netstacks-plugin-alerts:1.0.1, port 8080, capabilities read_devices, invoke_llm, trigger_agent) and Health Status running and healthy

The health status is read from Docker each time you open the page.

Update a Plugin

To move to a new version of a plugin, replace it while keeping its data:

  1. Open the plugin's row on the Plugins page and click Uninstall. From the list page, uninstall always keeps the plugin's data.
  2. Click Upload Plugin and upload the new .nspkg.
  3. Click Enable.

The Controller tracks which migrations have already run for each plugin, so only the new version's new migration files are applied. Plugin settings are stored with the installed plugin record; re-enter them after the update if the plugin has any.

Uninstall a Plugin

  • From the Plugins list: click Uninstall, then confirm in the Uninstall Plugin dialog. The container is removed and the plugin is unregistered, but its database schema and data are kept.
  • From the plugin detail page: click Uninstall. The dialog has an extra checkbox, Also purge all plugin data. Select it to also delete the plugin's database schema and everything in it (for example all alerts or incidents). This can't be undone.

Where Plugin Screens Appear

A plugin declares panels in its manifest. Each enabled plugin's panels show up in two places:

Admin console: the Plugins sidebar section

The left sidebar gets a Plugins section with one entry per panel — for the NetStacks plugins: Alerts, Pipeline Rules and Incidents. Each entry opens /plugin/<plugin>/<panel>, a read-only table of the plugin's data that refreshes automatically.

Admin console Incidents panel at /plugin/incidents/incident-list, a read-only table with Title, Severity, State, Alerts, ITSM ID and Created columns

Terminal: the activity bar

In the Terminal (desktop app or the web terminal at /terminal/) connected to the Controller, each panel gets an icon in the left activity bar. The alerts plugin adds the bell icon (Alerts) and the incidents plugin adds the warning-triangle icon (Incidents). These are the full working views: you can open alert and incident details, change states, link alerts and add comments.

Terminal with the Incidents panel open from the warning-triangle icon in the activity bar, showing two incidents with severity and state badges

Panels from other plugins appear in the Terminal as a table, with any buttons the plugin defines.

Troubleshooting

“Plugin system requires Docker”

Docker isn't reachable from the Controller. Start Docker on the host and restart the Controller.

A plugin is in the error state

Open the plugin's detail page to read the error. Common causes are an image that failed to build or a container that exits on start. Check the container's logs on the Controller host with docker logs netstacks-plugin-<name>, fix the cause, then click Enable again.

“Plugin '<name>' not found or not enabled”

The plugin's API answered this because the plugin is disabled, or isn't installed in your current organization. Switch to the right organization or enable the plugin.

Plugin panels don't show in the Terminal

Make sure the Terminal is connected to the Controller and you are in the organization where the plugin is enabled. Panels appear only for enabled plugins.