Plugin Architecture

Noxus runs plugin code inside isolated sandboxes, separate from the core platform. This keeps the platform stable — and safe — while letting plugins use any dependencies and run arbitrary logic.

​

High-level overview

The Noxus Backend manages plugin records (install, uninstall, status) and provisions each plugin’s sandbox. The Backend and every Worker call plugin nodes during execution. The Sandbox Manager bridges them to the plugin’s worker process — and multiplexes their requests, so all platform processes share one warm worker per plugin.

​

Sandboxed workers

Each installed plugin gets its own sandbox. The platform provisions it once:

1. Download the plugin source (Git repo, upload, or marketplace)
2. Upload the source tree into the sandbox
3. Install its dependencies there, in a uv virtual environment
4. Start noxus plugin worker — a long-lived process speaking JSON-RPC over stdio

The worker stays warm: the plugin’s module graph is imported once, so each subsequent node execution is a single round trip rather than a process start. If the sandbox is ever reaped, the next call transparently re-provisions it. Because plugin code is untrusted, it runs with no platform credentials and typically no network route back to the platform. Anything it needs from the platform — reading or writing a file — it asks for over the same channel (see File handling below).

​

Editing a plugin without reinstalling

Because the venv lives in the sandbox and survives a worker restart, updating a plugin’s code is cheap: sync the changed files into the sandbox and restart the worker. Dependencies are only reinstalled when the plugin’s dependency list actually changes. This is what makes an edit-and-run loop practical.

​

Plugin lifecycle

​

Status flow

Plugins go through these statuses:

​

Plugin sources

Plugins can be installed from multiple sources:

​

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 their call() is forwarded to the plugin’s worker instead of executing locally. Each plugin runs as a long-lived worker process inside its own sandbox. The plugin’s module graph is imported once and stays warm, so a node execution costs one round trip rather than a process start. The backend and every worker replica share that same warm worker through the sandbox manager, which multiplexes their requests over one channel per plugin.

​

Plugin worker internals

The plugin worker (noxus plugin worker, generated by the SDK) speaks line-delimited JSON-RPC over stdin/stdout. It answers: The SDK discovers the plugin class and wires these up automatically — you never write transport code. For local authoring, noxus plugin serve exposes the same operations over HTTP. Note that platform file access is unavailable when serving locally, since files live on the platform.

​

File handling

Plugins run inside a sandbox with no direct access to the platform’s storage — and typically no network route back to it either. Instead, file operations travel back along the same channel the platform used to call the plugin: The platform services these callbacks in-process against its own storage. Each call carries a single-use token the platform minted, which is how it knows which workspace the request belongs to — a plugin can only read and write files in the workspace of the run it is executing for. Inside plugin code, you use the File class and the execution context’s file helper — the SDK handles all the bridging transparently.

​

Security model

• Each plugin runs inside its own sandbox (gVisor/syd), with its own dependencies and filesystem
• Plugin code has no platform credentials — the sandbox holds no API keys
• File access is scoped to the calling workspace via a single-use token minted per call
• 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