Skip to main content
formae uses a plugin architecture to extend its capabilities. Plugins add support for infrastructure formae doesn’t manage out of the box, without changing formae’s core.

​
How plugins work

Plugins run as separate processes that communicate with the formae agent. When the agent starts, it discovers installed plugins and spawns them. Each plugin announces its capabilities (supported resource types, rate limits), and the agent routes resource operations to the right plugin based on resource type. This architecture gives you:
  • Isolation: a plugin crash doesn’t take down the agent or other plugins.
  • Independent updates: update a plugin without updating formae itself.
  • Extensibility: anyone can build a plugin for infrastructure formae doesn’t yet support.
  • Independent licensing: plugins are licensed separately from formae.

​
Plugin types

A plugin is one of two types, declared in its manifest:
  • Resource plugins manage cloud provider resources, for example aws, azure, gcp. They run only on the agent host, since that’s where orchestration happens. A resource plugin bundles its own Pkl schema (schema/pkl/) alongside its binary, so installing the plugin is what makes its resource types available in your forma files.
  • Auth plugins, for example auth-basic, construct and verify the authentication header used on every CLI-to-agent request. Because both sides of that exchange need to agree, an auth plugin must be installed at the same version on both the agent host and every CLI host.
Earlier versions of formae described a third “network” plugin role (Tailscale mesh networking as a plugin). Tailscale is now configured directly on the agent as a network config block, not installed as a plugin. See Security & networking for setup.

​
Plugin location

Plugins install into /opt/pel, organized by namespace and version:
/opt/pel is root-owned and the agent runs as the pel user, so formae plugin install, uninstall, and update typically need sudo. When the agent starts, it discovers and loads every plugin under this tree.
formae plugin install runs locally, on the host you invoke it from. For an agent deployed via a cloud installer (ECS, ACI, Cloud Run, Helm/K8s) there’s no host to install onto directly, bake the plugin into a derived agent image instead.

​
Example: the AWS plugin

The aws plugin lets formae manage AWS resources. Once installed, you can use AWS resource types in your forma:

​
Listing plugins

Each row shows whether the plugin lives on the agent, the CLI, or both, and flags a version mismatch if an auth plugin has drifted between the two. See the plugin CLI reference for search, info, install, uninstall, and update.

​
Building your own plugin

If you need to manage resources in a system formae doesn’t support yet, build a plugin. A plugin implements CRUD operations (Create, Read, Update, Delete) and discovery for its resource types; formae handles orchestration, ordering, and rate limiting around it. See Extending formae for how to get started.

​
See also

  • Target: where a plugin’s resources get deployed.
  • Apply modes: how the agent uses a plugin’s Create/Update/Delete operations during an apply.