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

Terminal
marfa plugins install tickets
installed tickets 0.0.13 with 5 types

The 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.13

A 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:

AnswerWhy
409 plugin_narrowsThe version would remove or narrow something; details.changes names each change.
409 plugin_version_olderThe version is older than the one installed.
409 plugin_child_conflictThe 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:

AnswerWhy
409 plugin_needs_newer_serverThe plugin needs a later Marfa: upgrade first.
409 type_existsThe instance already holds one of the plugin's types, and the plugin didn't install it.
409 connector_source_heldAnother plugin's connector, a connector you run yourself or a key already holds the source the plugin's connector names. details names which.
403 forbiddenA 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.

Terminal
marfa plugins remove tickets
removed tickets; its 5 types and their items stay

Removing 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.

On this page