Install a plugin
Add a plugin's shared types, with the guidance agents read and the edge types they use, to your instance by name or from a file, update it, and remove it.
A plugin adds types that every app and agent can share, such as tickets, under common. Each type comes with guidance that tells an agent how to fill it, and the plugin brings the edge types they use and, for some, a connector. Only a plugin adds a common type. You need the CLI signed in to your instance, as the Quickstart leaves you.
Install by name
marfa plugins install ticketsinstalled tickets 0.0.13 with 5 typesThe CLI reads the plugin from the latest release of withmarfa/plugins. The release's plugins.json lists each plugin with the SHA-256 of its bundle, and the CLI checks the bundle before it sends it to your instance, which fetches nothing itself. A bundle that doesn't match, or a release the CLI can't read, exits 3 with plugins_unreachable and installs nothing. MARFA_PLUGINS_URL names another release address.
Installing is one write: every type and edge type of the plugin goes in, or none does. Each type then names its plugin: marfa types get common.ticket answers provenance.origin as plugin, and provenance.plugin with the name and version.
Install from a file or a folder
A bundle, <name>.plugin.json, installs as it is. A plugin's source folder is built into one first, and the CLI prints the SHA-256 of what it built:
marfa plugins install ./tickets.plugin.json
marfa plugins install ./tickets --version 0.0.13A folder installs at 0.0.0 without --version. Plugin format says what a folder and a bundle hold.
Update a plugin
Install it again. The same version answers tickets 0.0.13 is already installed and changes nothing. A newer version may only add, such as fields, status words, enum values and types:
| Answer | Why |
|---|---|
409 plugin_narrows | The version would remove or narrow something; details.changes names each change. |
409 plugin_version_older | The version is older than the one installed. |
409 plugin_child_conflict | The version gives a type a field that one of your own types beneath it declares differently. Change your type, then install again. |
What installing needs
Your own sign-in can install any plugin. A key needs schema.write, write on each of the plugin's types and edge types, and connectors.manage when the plugin has a connector. Only you write guidance, so an app's sign-in, or a key an app made, is refused 403 forbidden for a plugin whose types carry it. A first install is also refused:
| Answer | Why |
|---|---|
409 plugin_needs_newer_server | The plugin needs a later Marfa: upgrade first. |
409 type_exists | The instance already holds one of the plugin's types, and the plugin didn't install it. |
409 connector_source_held | Another plugin's connector, a connector you run yourself or a key already holds the source the plugin's connector names. details names which. |
403 forbidden | A type sits under core, system, marfa, app or user, which details.namespace names. |
A plugin's connector runs on a connector host you link to your instance: Run a plugin's connector.
List and remove plugins
marfa plugins list shows every plugin installed, and marfa plugins get tickets one, with its types and the fingerprint of the bundle it came from.
marfa plugins remove ticketsremoved tickets; its 5 types and their items stayRemoving a plugin deletes no item. Its types, edge types and items stay, and keep naming the plugin; a connector it brought stops, and its settings and mapping go (Remove a host or a plugin). Change a type deletes a type you no longer want. Exports and backups carry the plugins installed.
The rules behind this page are in the plugins chapter of the contract.