Creating Configurable Plugins

Noxus renders configuration forms for you from typed schemas — no frontend code. There are three levels of configuration, all built with the NCL config language (Parameter + display= widgets) from noxus_sdk.ncl:

Plugin-level config — settings that belong to the whole plugin.
Node config — per-node settings, including bindable inputs.
Dynamic config — config computed server-side at edit time.

Plugin-level configuration

Plugin config lives on a PluginConfiguration subclass, which you pass as the type parameter of BasePlugin[...]. Its fields are Parameter(...) — the same NCL widgets you use everywhere.

from noxus_sdk.ncl import ConfigNumber, ConfigText, ConfigToggle, Parameter
from noxus_sdk.plugins import BasePlugin, PluginConfiguration
from noxus_sdk.schemas import ValidationResult

class WeatherPluginConfig(PluginConfiguration):
    units: str = Parameter(default="metric", display=ConfigText(label="Units"))
    api_timeout: int = Parameter(default=30, display=ConfigNumber(label="API timeout (s)"))
    enable_caching: bool = Parameter(default=True, display=ConfigToggle(label="Enable cache"))

    def validate_config(self) -> ValidationResult:
        if self.api_timeout < 1:
            return ValidationResult(valid=False, errors=["Timeout must be >= 1"])
        return ValidationResult(valid=True)

class WeatherPlugin(BasePlugin[WeatherPluginConfig]):
    name = "weather"
    display_name = "Weather"
    version = "1.0.0"
    description = "Weather nodes"
    author = "You"
    # nodes(), integrations(), ...

Override validate_config to gate the install. When a plugin declares config, the platform calls validate_config before moving the plugin to running — if it returns valid=False, or if config was never set, the plugin sits in missing_config until an admin provides a valid configuration.

Reading plugin config in a node

Plugin config is delivered to every call on the execution context as ctx.plugin_config (a dict of the saved values):

async def call(self, ctx: RemoteExecutionContext, city: str) -> dict:
    units = ctx.plugin_config.get("units", "metric")
    timeout = ctx.plugin_config.get("api_timeout", 30)
    return {"temp": 22 if units == "metric" else 72}

Node configuration with NCL

Node config is a NodeConfiguration subclass; each field is a Parameter(...) with an optional display= widget. Values round-trip to the worker and reach the node as self.config.

from noxus_sdk.ncl import ConfigNumber, ConfigSelect, ConfigToggle, Parameter
from noxus_sdk.nodes.base import NodeConfiguration

class ScraperConfig(NodeConfiguration):
    provider_from_input: bool = Parameter(
        default=False,
        display=ConfigToggle(label="Receive provider as input"),
    )
    source: str = Parameter(
        default="acme",
        display=ConfigSelect(label="Source", values=["acme", "globex", "initech"]),
    )
    max_pages: int = Parameter(
        default=5,
        display=ConfigNumber(label="Max pages"),
    )

Common widgets from noxus_sdk.ncl:

Widget	Renders
`ConfigText`	single- or multi-line text (`is_textarea`, `number_of_lines`)
`ConfigPassword`	masked secret input
`ConfigNumber` / `ConfigNumberRange`	numeric input / bounded numeric input (`min`, `max`)
`ConfigToggle`	boolean switch
`ConfigSelect` / `ConfigMultiSelect`	single / multi choice (`values=[...]`)
`ConfigDivider`	visual separator

Fields without a display still render with a default widget for their type.

Conditional visibility with `VisibleIf`

Show or hide a field based on another field’s value with a VisibleIf rule (noxus_sdk.ncl) — evaluated in the form as the user edits, no round-trip:

from noxus_sdk.ncl import VisibleIf

source: str = Parameter(
    default="acme",
    display=ConfigSelect(label="Source", values=["acme", "globex"]),
    # Only shown when provider_from_input is False
    rules=[VisibleIf(config_source="provider_from_input", value=False)],
)

Bindable inputs (V2 nodes)

On a V2 node, mark a config field Parameter(bindable=True) to make it a bindable input — in the editor it accepts a literal or a :var[...] reference to an upstream output. It still arrives on self.config. See the overview for the full V2 node shape.

Dynamic configuration (`get_config`)

To compute config server-side at edit time — e.g. fetch select options from an upstream API, or toggle field/connector visibility based on other values — override get_config. It runs in the worker; mutate the response and return it.

from noxus_sdk.nodes.schemas import ConfigResponse

class MyNode(BaseNode[MyConfig]):
    @classmethod
    async def get_config(
        cls,
        ctx: RemoteExecutionContext,
        response: ConfigResponse,
        skip_cache: bool = False,
    ) -> ConfigResponse:
        response.config_values["choice"] = ["alpha", "beta"]
        return response

The response exposes config (the serialized fields), config_values (the saved values), and — for V1 nodes — inputs/outputs you can flip visible on. The platform only wakes the worker for this when a ConfigSelect has no static values, so static nodes never pay the round-trip.

Runtime Safety

Validate at the boundary. Use validate_config on plugin config and NodeConfiguration field types to reject bad input before it reaches your code.
Sanitize before external calls. Never interpolate raw config strings into shell commands, URLs, or queries unchecked.
Mask secrets. Any credential-like field must use ConfigPassword so it is hidden in the form. For true integration secrets, prefer an integration credential over a config field.

Publishing & Versioning

Package, version, and roll out configuration changes safely.

Overview

Tutorial

Reference

GitOps

Plugin-level configuration

Reading plugin config in a node

Node configuration with NCL

Conditional visibility with `VisibleIf`

Bindable inputs (V2 nodes)

Dynamic configuration (`get_config`)

Runtime Safety

Publishing & Versioning

​Plugin-level configuration

​Reading plugin config in a node

​Node configuration with NCL

​Conditional visibility with VisibleIf

​Bindable inputs (V2 nodes)

​Dynamic configuration (get_config)

​Runtime Safety

Publishing & Versioning

Plugin-level configuration

Reading plugin config in a node

Node configuration with NCL

Conditional visibility with `VisibleIf`

Bindable inputs (V2 nodes)

Dynamic configuration (`get_config`)

Runtime Safety