Plugin

formae uses a plugin architecture to extend its capabilities. Plugins allow you to add support for yet unsupported infrastructure technologies without modifying the core formae system.

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 as child processes. Each plugin announces its capabilities, and the agent routes resource operations to the appropriate plugin based on resource type.

This architecture provides:

  • Isolation - Plugin crashes don't affect the agent or other plugins
  • Independent updates - Update plugins without updating formae
  • Extensibility - Anyone can build plugins for infrastructure not yet supported by formae
  • Licensing - Plugins are licensed independently from formae

Plugin Types

Each plugin can have one or more roles:

  • Resource management - Manage cloud provider resources (example: aws plugin for AWS infrastructure)
  • Schema processing - Add support for configuration languages (example: pkl plugin for Pkl syntax)
  • Network operations - Enable networking features (example: tailscale plugin for secure mesh networking)

Plugin Location

Plugins are installed to the standard plugin directory:

~/.pel/formae/plugins/

Each plugin is organized by namespace and version:

~/.pel/formae/plugins/
├── AWS/
│   └── v0.80.0/
│       ├── aws              # Plugin binary
│       ├── formae-plugin.pkl
│       └── schema/pkl/
└── MYCLOUD/
    └── v1.0.0/
        ├── mycloud
        ├── formae-plugin.pkl
        └── schema/pkl/

When formae starts, it automatically discovers and loads all plugins from this location.

Example

AWS Plugin: The aws plugin enables formae to manage AWS resources. Once loaded, you can use AWS resource types in your forma:

import "@aws/s3/bucket.pkl"

new bucket.Bucket {
  label = "my-bucket"
  bucketName = "my-unique-bucket-name"
}

Listing Plugins

To see which plugins are currently active:

formae plugin list

Output:

aws 0.80.0 resource
pkl 0.80.0 schema

Building Your Own Plugin

If you need to manage resources in a system that formae doesn't support yet, you can build your own plugin. Please refer to Extending formae for how to get started.