Installing plugins¶
A plugin can be asked for in four ways:
Spec |
Where from |
|---|---|
|
by name, from a plugin index |
|
its repository: the newest version tag |
|
a tag (or a commit) |
|
a folder, while writing a plugin ( |
|
PyPI, for plugins also published there |
Before anything is installed, noodlelab resolves the plugins and the plugins they require into a plan and shows it: each plugin, its version, where it comes from (repository and commit), its trust level and the permissions it asks for. Nothing is installed until you agree.
In the admin portal¶
Admin → Plugins lists the installed plugins with their health, and lets an admin:
Browse the plugin indexes and install one;
Add from URL: install from a git repository (unverified: see Security);
upgrade, remove, disable, enable and test (run its example graphs) a plugin;
grant the permissions a plugin asks for;
set the Policy: where plugins may come from, the least trusted plugin allowed, private indexes, and which plugins run in noodlelab’s own process (the others run in the sandbox).
A new plugin’s nodes appear in open editors straight away. An upgrade or a
removal needs a restart (Python cannot unload code): the page says so, and
Restart now restarts a server started with noodlelab serve.
The server pins what it installed in noodlelab-plugins.lock in its home
folder, and installs any that are missing when it starts, so a server in a
container gets its plugins back after the container is rebuilt.
The official plugins (maths, science, engineering…) are released on PyPI with noodlelab, and update with it: their Update to… button opens the Updates dialog, which installs them from PyPI together with the noodlelab they need, even before the plugin index lists the new version. See Updates.
The editor shows a light in its toolbar: green when every plugin is healthy, amber when a restart or update waits, red when a plugin failed to load or the open graph needs one that is missing.
Graphs that need plugins¶
A saved graph records the plugins its nodes come from, in its metadata:
plugins has the range of versions each should work with (the version it was
saved with, up to the next major version), and plugin_sources says where
each came from, as noodlelab plugins add takes it:
"plugins": {"thermo": ">=1.3.0,<2", "steam": ">=0.4.1,<0.5"},
"plugin_sources": {
"thermo": {"distribution": "noodlelab-thermo", "version": "1.3.0", "kind": "index", "source": "thermo"},
"steam": {"distribution": "noodlelab-steam", "version": "0.4.1", "kind": "git",
"source": "git+https://github.com/someone/noodlelab-steam@v0.4.1", "commit": "…"}
}
A plugin installed from a local folder is recorded with an empty source: it
cannot be fetched anywhere else. Plugins that come with noodlelab are left out.
Opening a graph that needs plugins this server does not have (or has in another version, or disabled) shows them in a dialog, with where each came from. An admin can Install all: the plan, trust and permissions are shown for approval as for any other install, then the graph opens again with its nodes, without reloading the page. Anyone else sees the commands to ask an admin for. Nothing is ever installed only because a graph names it, and a git URL a graph names is shown in full before it is approved. Until the plugins are installed, the graph is not saved over (its nodes would be lost).
The tutorial works the same way: a chapter that uses nodes from a plugin that is not installed starts by installing it.
On the command line¶
noodlelab plugins search thermo # the plugin indexes
noodlelab plugins add thermo # and whatever it requires; shows the plan, asks
noodlelab plugins add "thermo>=1.2,<2" --yes
noodlelab plugins add git+https://github.com/someone/noodlelab-thermo
noodlelab plugins list # versions, trust, health
noodlelab plugins check # health; exit code 1 if anything is wrong (for CI)
noodlelab plugins upgrade # every plugin, to the newest version that fits
noodlelab plugins remove thermo # refused while another plugin requires it
noodlelab plugins disable thermo # keep it installed, but do not load it
noodlelab plugins lock # pin what is installed
noodlelab plugins sync # install exactly what the lockfile pins
The commands install into the Python environment noodlelab runs in, with uv
when it is there (pip otherwise). The lockfile is noodlelab-plugins.lock in
the current folder when there is one (a project pinning its plugins), and in
noodlelab’s home otherwise.
In Python¶
Plugins are found through their entry points, so a script using
noodlelab.verify or running graphs sees every installed plugin; nothing
needs registering. A script can say what it needs, and fail early with the
command that installs it:
import noodlelab.plugins
noodlelab.plugins.require("thermo>=1.2", "geo")
In a notebook, noodlelab.plugins.install("thermo") shows the plan and asks,
and noodlelab.plugins.health() returns what plugins check prints.
From agents (MCP)¶
noodlelab mcp offers list_plugins, search_plugins, install_plugin and
remove_plugin. An agent can install only plugins from an index that ask for
no permissions, and only when the MCP server is started with
NOODLELAB_MCP_ALLOW_INSTALL=1 (or it is attached to an editor, and its token
is an admin’s). For anything else the tool returns the command for the user to
run. check_graph names the plugins a graph needs that are missing. When
attached to an editor, list_plugins also says where the MCP server’s plugins
differ from the editor’s.