1. Plugin Definition

This is part 1 of the Your First Plugin tutorial.

A plugin is an installable Python package that adds nodes, integrations, triggers, and datasources to the platform. At install time the platform reads the plugin’s manifest (derived from your code — never hand-written), provisions a sandbox, and runs your plugin as a warm worker. The plugin class is the entry point that ties everything together.

Scaffold the project

Use the Noxus CLI to generate a plugin from the template:

pip install noxus-sdk
noxus plugin create --output-dir ./my-plugins

create is interactive — it prompts for a few values and expands a template:

plugin_name [my-plugin]: weather-plugin
description [A new Noxus plugin]: Provides weather data nodes
author_name [Your Name]: Your Name
Select include_integration [yes]: no

This produces the following structure (package names are derived from plugin_name):

weather-plugin/
├── weather_plugin/
│   ├── __init__.py            # the plugin class lives here
│   └── nodes/
│       ├── __init__.py
│       └── weather_plugin_node.py   # an example node
├── tests/
│   └── __init__.py
├── pyproject.toml
└── README.md

There is no manifest.json in the scaffold. The manifest is generated from your code — see Generate the manifest below. Never write or edit it by hand.

Prefer to start from scratch? A plugin only needs a package with your plugin class plus a pyproject.toml. Here’s a minimal pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "weather-plugin"
version = "0.1.0"
description = "A weather data plugin for Noxus"
requires-python = ">=3.11"
dependencies = [
  "noxus-sdk>=0.5.1",
  "httpx>=0.27.0",
]

Keep noxus-sdk at or above the platform’s version. The sandbox resolves noxus-sdk alongside your dependencies; pinning an older floor can make the worker fail to start.

Define the plugin class

Open weather_plugin/__init__.py. A plugin subclasses BasePlugin[YourConfig] and returns the components it provides from nodes(), integrations(), triggers(), and datasources():

from noxus_sdk.plugins import BasePlugin, PluginConfiguration
from noxus_sdk.plugins.types import PluginCategory


class WeatherPluginConfig(PluginConfiguration):
    """Plugin-level configuration — empty for now."""
    pass


class WeatherPlugin(BasePlugin[WeatherPluginConfig]):
    name = "weather-plugin"
    display_name = "Weather Plugin"
    version = "0.1.0"
    description = "Provides weather data nodes and integrations"
    category = PluginCategory.GENERAL
    author = "Your Name"

    def nodes(self):
        return []  # We'll add nodes in the next section

    def integrations(self):
        return []  # We'll add integrations later

Every plugin defines this metadata:

Field	Required	Description
`name`	Yes	Unique identifier used for lookups, dependencies, and storage
`display_name`	Yes	Human-readable name shown in the UI
`version`	Yes	Semantic version string (e.g. `"0.1.0"`)
`description`	Yes	Short description of what the plugin does
`author`	Yes	Author name
`category`	No	`PluginCategory.GENERAL`, `.DOCUMENT`, or `.OTHER` (default `.OTHER`)
`execution`	No	`"runtime"` (default), `"docker"`, or `"remote"`

The four provider methods return lists of classes your plugin exposes. A plugin must provide at least one node, integration, trigger, or datasource:

Method	Returns
`nodes()`	`list[type[BaseNode]]` — V1 and V2 nodes may be mixed freely
`integrations()`	`list[type[BaseIntegration]]`
`triggers()`	`list[type[BasePollingTrigger]]`
`datasources()`	`list[type[BaseDataSource]]`

We’ll populate nodes() in the next section.

Validate the structure

noxus plugin validate --path ./weather-plugin

validate imports your plugin class, generates the manifest in memory, and reports any errors or warnings. Run it often as you develop. Add --strict to make warnings fail too.

Generate the manifest

The manifest is the install-time contract, derived entirely from your code. Generate manifest.json with:

noxus plugin generate-manifest --path ./weather-plugin

Regenerate it whenever a node, trigger, integration, or config signature changes. When you’re ready to ship, noxus plugin package --path ./weather-plugin bundles the source and a fresh manifest into an archive you upload via the platform’s Add plugin flow.

Run locally

For a quick local authoring loop, serve the plugin over HTTP:

noxus plugin serve --path ./weather-plugin

You’ll see output like:

PLUGIN_PORT:8505
INFO:     Started server process
INFO:     Waiting for application startup
INFO:     Application startup complete

Visit http://localhost:8505/health to verify it’s running, or http://localhost:8505/manifest to inspect the generated manifest.

serve is a local authoring aid. On the platform, plugins don’t run as an HTTP server — they run as sandboxed JSON-RPC workers, and file operations (reading or writing platform files) are only available there, not under serve. Use serve to iterate on node logic that doesn’t touch platform files; use the install flow to exercise the full runtime.

The plugin won’t do much yet — let’s add a node.

Next: First Node →

Create your first node with bindable inputs, typed outputs, and logic.

Overview

Tutorial

Reference

GitOps

Scaffold the project

Define the plugin class

Validate the structure

Generate the manifest

Run locally

Next: First Node →

​Scaffold the project

​Define the plugin class

​Validate the structure

​Generate the manifest

​Run locally

Next: First Node →

Scaffold the project

Define the plugin class

Validate the structure

Generate the manifest

Run locally