> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> How formae extends itself to new infrastructure through separate, independently versioned plugin processes.

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.

<Note>
  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](/documentation/reference/security-and-networking) for setup.
</Note>

## Plugin location

Plugins install into `/opt/pel`, organized by namespace and version:

```
/opt/pel/
├── AWS/
│   └── v0.1.5/
│       ├── aws              # Plugin binary
│       ├── formae-plugin.pkl
│       └── schema/pkl/
└── MYCLOUD/
    └── v1.0.0/
        ├── mycloud
        ├── formae-plugin.pkl
        └── schema/pkl/
```

`/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.

<Warning>
  `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.
</Warning>

## Example: the AWS plugin

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

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
import "@aws/s3/bucket.pkl"

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

## Listing plugins

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae plugin list
```

```
Resource plugins:
  ✓ aws            0.1.5  (agent + cli)
  ✓ azure          0.1.2  (agent + cli)

Auth plugins:
  ✓ auth-basic     0.1.0  (agent + cli)
```

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](/documentation/reference/cli) 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](/documentation/concepts/target): where a plugin's resources get deployed.
* [Apply modes](/documentation/concepts/apply-modes): how the agent uses a plugin's Create/Update/Delete operations during an apply.