Custom Nodes on Desktop

You can extend BioNodulo with your own nodes by dropping Python files into the local custom_nodes/ directory. This page covers the desktop workflow — where files go, how discovery works, and what to do when a node doesn’t show up. For the full node API (BaseNode, CommandNode, INPUT_TYPES, typed ports, and execution semantics), see the Node Reference → Custom Nodes Guide.

Create a local custom node

1. Find the custom nodes directory. By default it is ./custom_nodes inside your project root; you can change it with custom_nodes_dir in bionodulo.yaml.

2. Copy the bundled example as a starting point:

   cp custom_nodes/example_node.py.example custom_nodes/my_node.py

3. Edit the file. Any class that subclasses CommandNode or BaseNode and sets a NODE_ID is registered automatically — the example file contains five annotated templates, from a minimal command wrapper to a pure-Python node with no external tools.

4. Restart BioNodulo. Custom nodes are discovered at startup and appear in the node palette under their declared CATEGORY, searchable by SEARCH_ALIASES.

No registration code is needed — defining the class is enough. The example’s GIT_URL placeholder is source metadata (see below), not an install instruction.

Package-based nodes

For anything beyond a single file, use a package layout:

custom_nodes/my_package/
    __init__.py        # imports your node classes so they register
    nodes.py
    requirements.txt   # optional; pip-installed on Git installs
    bionodulo.toml     # optional package manifest

The optional bionodulo.toml manifest declares package metadata:

[package]
name = "my-package"
version = "0.1.0"          # name and version are required
description = "My nodes"
repository = "https://github.com/you/my-package.git"
entrypoints = ["nodes.py"]
requirements = []

Packages with a valid manifest show up in the manager’s installed-package listing with their metadata; plain .py files and __init__.py directories are listed as legacy packages.

Source metadata: GIT_URL and GIT_COMMIT

Custom node classes should declare where their source lives:

class MyNode(CommandNode):
    NODE_ID = "my_node"
    GIT_URL = "https://github.com/yourusername/your-bionodulo-nodes.git"
    GIT_COMMIT = ""  # optional: pin to a specific commit hash

When a workflow is saved, BioNodulo records each node’s GIT_URL and GIT_COMMIT (along with its required executables and Python requirements) into the workflow manifest. If the workflow is later opened on a machine where the node isn’t installed, the dependency resolver can report exactly which source repository provides it.

Troubleshooting: node doesn’t appear in the palette

• Restart the app. Custom nodes are loaded at startup; a running instance won’t pick up new files until it reloads the registry.
• Check the location. The file must be inside the configured custom_nodes_dir (see Configuration).
• Check the class. The node must subclass CommandNode or BaseNode and define a unique NODE_ID — a name that collides with a built-in node won’t register cleanly.
• Check for import errors. A syntax error or failing import in your file prevents every node in it from registering; look at the app logs (Help → Open Logs) for the traceback.
• Workflows reference missing nodes. If you open a workflow that uses a node you don’t have installed, it shows up in the missing-dependencies report as “Custom node <type> is not installed”, with its source GIT_URL when one was recorded. See Managing Environments.

Next

• Custom Nodes Guide (full node API)
• Creating Custom Nodes (authoring walkthrough)
• Adding Custom Nodes (overview)