Install a plugin

The Plugins page can install a plugin from a package name, a GitHub address or a folder on this computer. This page follows that install: what the app checks first, how the run reports itself, and what to do when it stops.

Install a plugin from the Plugins page

The Plugins page and its sidebar entry appear when the Plugins page feature is on in Settings > Developer > Advanced features; Advanced features holds that switch. When this installation runs without a manageable profile, the page reads This deployment runs without a manageable profile, so plugins cannot be installed or switched here.

Open Plugins in the sidebar and choose Add plugin.
In Package name or address, enter the plugin's package name (it can carry a version), a GitHub repository address, or the path to a local plugin folder. The field shows the example for example @acme/datamind-plugin.
For the exact forms, expand Install guide and examples: it shows Package name, GitHub repository address and Local plugin directory, each with an example and a Use example button.
Open Registry if you want to change where the package is fetched from; the next section covers the choices.
Choose Install. The app reads the address first, with Checking… on the button, then starts the run.
When the run finishes, choose Enable now to switch the plugin on right away, or Done to leave it off for now.

Pressing Enter in the field starts the check too. The dialog carries a warning about what you are adding: Install only plugins you trust: they run with your permissions and can damage DataMind Oda or leak your data.

To ask Oda to install a plugin in a chat instead, see Plugins and bundles.

Where the install gets the package

Registry beside the field names the source the install asks first.

The offered list holds Default registry, the source this installation is set up with, the mirrors it offers, and Custom address.
A Custom address must start with http:// or https://; anything else is refused with Enter an address starting with http:// or https://.
Your last choice starts the next dialog; an address the installation no longer offers stays as a typed one.
When the first source cannot serve the package, the run says so and asks the next one: {previous} could not serve the package; retrying through {registry} (registry {index} of {total}).
When no source could be reached, the message names every one tried: No registry could be reached (tried: {registries}); check the network or proxy settings, or change the registry.
A registry outside the offered set is asked alone. When the address you chose is not one of the installation's own sources and cannot serve the package, the run stops there instead of falling through to the others, so a name meant for a private source is never resolved from a public one. Within the offered set, the run asks the sources in turn and says which one it is asking.

What the check reports before anything downloads

The app reads the address you entered before downloading anything and refuses one it cannot accept. The sentence shows under the field, the address stays editable, and nothing is installed.

This is not a package name or address that can be installed: {reason}: not a form the app accepts.
This plugin is already installed: the plugin list already holds it.
No such plugin was found: no source has a package with that name.
The path does not exist or is not a valid plugin package: a local folder is missing or is not a plugin.
This package declares no bundle, so it cannot be installed as a plugin: {reason}: the package adds nothing Oda can load as a plugin.
The plugin registry could not be reached; check the network and try again: the source did not answer.
No registry could be reached (tried: {registries}); check the network or proxy settings, or change the registry: none answered, and every source tried is named.

Watch the install run

The installing screen shows the package's name, its one-line description and its version as the app read them.
Show install details folds the run's log; the terminal shows Running, Failed or Done, an exit line such as exit code {code}, and Copy, Copied and Collapse controls.
A long log folds after 12 lines, keeping the beginning and the end; expand it to read everything.
One install runs at a time; while a run is tracked, the page's main button reads View installation instead of Add plugin.
Cancel install stops a run while it still can: a cancellation during the download waits for confirmation, and once the app starts loading the bundle the run cannot be cancelled.
Closing the dialog hides it. The app asks to cancel when that is still possible; a run that is past that point finishes on its own and reports through a notice, and View installation reopens a tracked run.
A cancelled install changes nothing; the notice reads Installation cancelled; the plugin is not enabled, and downloaded files may remain. The app returns the package manifest and lockfile to what they were; files already downloaded can stay.
If the app cannot tell how a run ended, the screen says Installation status unconfirmed and offers Check installation status.

When the install finishes

The done screen reads one of:

Install finished with no new dependency.
Installed; it loads at the next start.
Install scripts allowed for {names}

Then:

Enable now switches the new bundle on, closes the dialog and scrolls its card into view.
Done closes the dialog. Closing without enabling leaves the plugin installed and off.
A successful install does not promise the plugin can start; if it fails to load, its row reports the problem, and Plugins and MCP connections covers switching and the states a row can show.
If the plugin connects another service through an MCP server, check it by using one of the server's tools; if it fails, repair the same plugin instead of installing another copy.

When an install fails

The failed screen shows one line, and Show install details holds the full output. Retry runs the install again. Change registry appears when the source was the problem and no scripts are waiting for permission; choosing it returns you to the address with the registry options open.

The network connection failed
No registry could be reached (tried: {registries}). Check the network or proxy settings, or change the registry and retry.
{host} could not be reached. A GitHub address or a .tgz link is not fetched through the registry: this machine must reach it directly or through a proxy. If the plugin is also published to npm, enter its package name instead.
No version matches the request
The disk is full; the install stopped
No write permission; the plugin cannot be installed
The downloaded package failed its integrity check
The install timed out
Something went wrong during the install; the details say what

Oda returns the package manifest and lockfile to what they were, so a failed install leaves the app as it was; files already downloaded can stay.

When packages want to run install scripts

Some dependencies want to run their own install scripts. The app does not run them on its own; the failed screen lists the packages and explains:

These packages have install scripts that pnpm did not run.
Once allowed, the scripts run here with your permissions, and the permission is saved in this profile.
Allow only packages you trust.

In place of Retry, the screen offers Allow these scripts and retry, which allows the scripts still waiting and retries the install. The permission is saved for these packages, so a later install of the same packages does not ask again.

Questions, answered

Can I install a plugin myself, without asking Oda?

Yes. Open Plugins in the sidebar and choose Add plugin; the page and its entry appear when the Plugins page feature is on in Settings > Developer > Advanced features. You can also ask Oda to install a plugin in a chat; Plugins and bundles covers that path.

What can I enter in the package field?

A package name, which can carry a version; a GitHub repository address; or the path to a local plugin folder. Install guide and examples shows each form with an example and a Use example button, and Enter in the field starts the check.

Which registry does the install ask, and can I change it?

The one chosen in Registry: Default registry, a mirror this installation offers, or a Custom address. Your last choice starts the next dialog. A custom address must start with http:// or https://.

Why does the check say the package declares no bundle?

The package holds nothing Oda can load as a plugin, so it is not installed. Check that the address names the plugin's own package; the full sentence is This package declares no bundle, so it cannot be installed as a plugin: {reason}.

Why did the install stop and ask me to allow scripts?

One of the package's dependencies wants to run its own install scripts, and the app does not run them on its own. The screen lists the packages, and Allow these scripts and retry allows the scripts still waiting and retries. Allowed scripts run with your permissions, so approve only packages you trust.

Where do I see why an install failed?

The failed screen shows one line, and Show install details holds the full output. Retry runs the install again, and Change registry appears when the source was the problem.

How do I cancel an install?

Choose Cancel install: a cancellation during the download waits for confirmation, and once the app starts loading the bundle the run cannot be cancelled. A cancelled install installs nothing, and the notice reads Installation cancelled; the plugin is not enabled, and downloaded files may remain.

Can I close the dialog while an install runs?

Yes, the dialog hides. The app asks to cancel when that is still possible; a run that is past that point finishes on its own and reports through a notice, and View installation reopens a tracked run.

What happens when an install finishes?

The done screen reads Install finished with no new dependency. or Installed; it loads at the next start. Then choose Enable now to switch the plugin on, close the dialog and scroll to its card, or Done to close and leave it off.

Why is my new plugin not running yet?

If you chose Done, or closed the dialog, the plugin is installed and off; switch it on on the Plugins page. A newly installed plugin loads at the next start of DataMind Oda, and a replaced package also needs a restart before its new code is used.