High-level overview
The Noxus Backend manages plugin records (install, uninstall, status). The Worker calls plugin nodes during workflow execution. The Plugin Server sits between them and the actual plugin processes, handling lifecycle management and request forwarding.Plugin Server
The Plugin Server is a standalone FastAPI service that orchestrates all plugin instances. It:- Installs plugins from various sources (Git repos, uploads, marketplace)
- Starts each plugin as an isolated process with its own Python environment
- Forwards execution requests from the platform to the correct plugin process
- Reports status back to the platform via webhooks
- Reconciles desired state with actual state on startup and periodically
Execution engines
The Plugin Server uses an engine abstraction to run plugins. Currently, the UV Process Engine is the primary engine: Each plugin gets its own virtual environment created byuv. The engine runs noxus plugin serve inside that environment, which starts a FastAPI server on an auto-assigned port. The engine reads the port from stdout and forwards all subsequent requests to that address.
Reconciliation
On startup, the Plugin Server reconciles with the platform to ensure running plugins match the desired state: The platform sends the full list of desired plugins with their expected status. The Plugin Server compares this against its running processes and takes the appropriate action — install, restart, uninstall, or do nothing.Plugin lifecycle
Status flow
Plugins go through these statuses:| Status | Meaning |
|---|---|
installing | Being downloaded and set up |
running | Healthy and serving requests |
missing_config | Needs configuration before it can work |
restarting | Being restarted (after update or error recovery) |
error | Failed — will be retried on next reconciliation |
uninstalling | Being removed |
uninstalled | Fully removed |
Plugin sources
Plugins can be installed from multiple sources:| Source | Use case |
|---|---|
| Git | Point to a Git repository (public or private with token). Supports branch, commit, and subdirectory targeting. |
| Upload | Upload a .tar.gz package directly through the UI. |
| Marketplace | Install from the official Noxus Plugins repository. |
| Local | Copy from a local directory (development only). |
How nodes execute through plugins
When a workflow runs a node that belongs to a plugin, here’s what happens: When a plugin is loaded, its manifest registers dynamic remote node classes in the platform’s node registry. These remote nodes look like normal nodes to the workflow engine but forward theircall() to the Plugin Server instead of executing locally.
Plugin process internals
Each plugin process is a FastAPI server generated by the SDK. It exposes:| Endpoint | Purpose |
|---|---|
GET /health | Health check |
POST /validate-config | Validate plugin configuration |
POST /nodes/{name}/config | Get dynamic node configuration |
POST /nodes/{name}/execute | Execute a node |
POST /integrations/{name}/config | Get integration configuration |
POST /integrations/{name}/ready | Check if integration credentials are valid |
noxus plugin serve command discovers the plugin class, loads its nodes and integrations, and generates all these routes automatically.
File handling
Plugins run in isolated processes without direct access to the platform’s storage. Files are transferred through the Plugin Server: Inside plugin code, you use theFile class and the execution context’s file helper — the SDK handles all the bridging transparently.
Security model
- Each plugin runs in its own isolated Python environment with its own dependencies
- Plugin processes bind to localhost only — they’re not directly accessible from outside
- The Plugin Server authenticates with the platform using an API key
- Integration credentials are passed through the execution context per-request, not stored in the plugin
- Plugin source downloads support private Git repositories with token auth