Install and manage modules

Supported package formats#

The web upload accepts .zip and .yamod. A yamod package is a ZIP alias, not a different binary format. A package contains module.json at the root, or inside one enclosing directory, plus a python/ implementation directory.

module.json
python/
  your_package/
    module.py

The web upload cap is 110 MiB. Extraction caps archive entries at 5000 and uncompressed content at 100 MiB. Traversal paths and Unix symlinks are rejected.

Validation#

The validator parses the external manifest, checks identity/entrypoint contracts and imports Python entrypoints. Primary METADATA name/version and declared permission codes must match the manifest.

Install and restart#

Administrator upload installs through staging/copy/move; replacement retains recoverable backups. New package installation requires restart before runtime discovery includes it. Python dependencies are declared but automatic pip installation is not verified.

Enable and disable#

Already discoverable modules can be enabled/disabled through the manager. Desired state is persisted and registry permissions activate/deactivate with loaded modules. Enablement validates required backend capabilities.

Health and diagnostics#

Inspect module settings, health and detail after startup. A loaded module without a backend is not equivalent to a healthy connected provider. Reported errors should guide configuration/provider checks.

Uninstall#

External package removal requires its modules to be disabled first. The package is moved to _module_backups and returns restart_required=true. Builtin removal uses a separate route that moves its directory to backup and persists an uninstall marker.

Implementation notes#

CLI verification detects ZIP by .zip suffix; the web handles .yamod through ZIP conversion. The parser does not enforce every published JSON schema property, and an external min_version compatibility floor is not proven to be enforced. See Module development.

Exact installation/management routes are in the Modules API category.