Publishing & Versioning

A plugin ships as an archive the platform reads at install time. This page covers what goes in the archive, how to install and update it, how versioning works, and how deployments without internet egress resolve dependencies.

What’s in the package

At the archive root the platform needs exactly three things:

my_plugin/__init__.py      # the plugin + its nodes / integrations / triggers
pyproject.toml             # name, version, dependencies (incl. noxus-sdk); packages = ["my_plugin"]
manifest.json              # generated from the code (never hand-written)

The upload installer reads manifest.json from the archive and fails without it, so it must be present and current.

Zip only source. Exclude .venv, __pycache__, .git, .ruff_cache, and node_modules. A stray .venv — easy to create by running uv inside the plugin dir — can balloon the archive from a few hundred KB to tens of MB.

Regenerate the manifest

The manifest is reflected from your code, not written by hand. Regenerate it whenever a node, trigger, integration, or config signature changes:

import json
from my_plugin import MyPlugin
json.dump(MyPlugin.get_manifest().model_dump(mode="json"),
          open("manifest.json", "w"), indent=2)

noxus plugin package and noxus plugin generate-manifest do this for you (see below). The manifest now also carries the plugin’s dependencies — captured from your pyproject.toml [project].dependencies at generation time — so the platform can display what the plugin will install.

Versioning

Noxus uses semantic versioning, defined once in pyproject.toml and mirrored into the manifest at generation time:

# pyproject.toml
[project]
name = "weather-plugin"
version = "1.2.0"          # Major.Minor.Patch
dependencies = [
    "noxus-sdk>=0.5.1",    # keep the floor at/above the platform's SDK version
    "httpx>=0.27",
]

SDK version alignment (required)

The sandbox resolves noxus-sdk alongside your other dependencies. If you pin an old SDK, it can win the resolution and the worker fails to start with No module named 'noxus_sdk.plugins.worker'. Always depend on noxus-sdk at or above the platform’s version (the platform installs a floor of at least noxus-sdk>=0.5.1), never an old floor.

Release Strategy

Validate

Confirm structure, definitions, and config schemas, and reflect the manifest.

noxus plugin validate --path ./my-plugin

Package

Regenerate the manifest and build the archive. noxus plugin package produces a .tar.gz; the platform’s upload flow also accepts .zip.

noxus plugin package --path ./my-plugin --output my-plugin-1.2.0.tar.gz

Install

Install into your Noxus deployment via one of the sources below.

Installing and updating

Open Settings → Plugins → Add plugin and choose a source:

Git

Push the tagged release to your repository, then point the platform at it (branch / commit / subpath as needed).

Upload

Drag the .tar.gz (or .zip) built by noxus plugin package into the upload tab.

Marketplace

Open a PR to github.com/Noxus-AI/noxus-plugins so the version is discoverable from the in-app marketplace.

On install the platform reads the manifest from the source, provisions the plugin’s sandbox, installs its dependencies, warms the worker, and reflects the manifest from the live worker. To pick up a new version of an already-installed plugin, use Reload on its row — the platform re-downloads the source and provisions a fresh sandbox.

Air-gapped / offline installs

Because the sandbox installs a plugin’s dependencies at provision time, a deployment with no internet egress needs those wheels available locally. The platform can serve them from a baked wheelhouse built into the sandbox image:

Setting	Default	Meaning
`PLUGIN_WHEELHOUSE_DIR`	`/opt/plugin-wheels`	Directory of pre-baked wheels. When present, deps install from it via `--find-links`. Ignored (falls back to PyPI) if the dir is absent, so it’s safe to leave on.
`PLUGIN_INSTALL_OFFLINE`	`false`	Air-gapped mode: install only from the wheelhouse, never PyPI. A plugin whose dependency isn’t baked fails fast instead of reaching out.
`PLUGIN_SDK_REQUIREMENT`	`noxus-sdk>=0.5.1`	The SDK spec installed into each sandbox; guarantees the worker entrypoint exists.

With a wheelhouse present but PLUGIN_INSTALL_OFFLINE off, deps resolve from the wheelhouse first and fall back to PyPI for anything not baked. For a fully air-gapped deploy, bake every dependency (including noxus-sdk) into PLUGIN_WHEELHOUSE_DIR and set PLUGIN_INSTALL_OFFLINE=true.

Compatibility Checklist

Inputs/Outputs: never remove or rename existing node inputs/outputs in a minor version; only add optional ones.
Config migration: give new config fields defaults so existing installs keep working.
Dependencies: keep the noxus-sdk floor aligned with the platform; for air-gapped targets, confirm new deps are in the wheelhouse before shipping.
Deprecation: mark old nodes as deprecated before removing them in a major version.

Plugins Overview

Return to the full plugin development map.

Overview

Tutorial

Reference

GitOps

What’s in the package

Regenerate the manifest

Versioning

SDK version alignment (required)

Release Strategy

Installing and updating

Git

Upload

Marketplace

Air-gapped / offline installs

Compatibility Checklist

Plugins Overview

​What’s in the package

​Regenerate the manifest

​Versioning

​SDK version alignment (required)

​Release Strategy

​Installing and updating

Git

Upload

Marketplace

​Air-gapped / offline installs

​Compatibility Checklist

Plugins Overview

What’s in the package

Regenerate the manifest

Versioning

SDK version alignment (required)

Release Strategy

Installing and updating

Air-gapped / offline installs

Compatibility Checklist