Extend the agent image

The base formae agent image at ghcr.io/platform-engineering-labs/formae ships with the standard plugin set: aws, azure, gcp, oci, ovh, and auth-basic. If you deploy through one of the cloud install guides to manage one of those clouds, you are done, with no extra steps. To manage anything else (grafana, datadog, k8s, gha, gitlab, compose, databricks, and so on) build a derived image that layers the plugin on top of the base, then point your deployment at the derived image. formae plugin install runs locally on the host that invokes it; for a cloud-deployed agent the derived image is the supported path.

Dockerfile pattern

ARG BASE_VERSION=0.87.1
FROM ghcr.io/platform-engineering-labs/formae:${BASE_VERSION}

USER root

RUN apt-get update && \
    apt-get install -y --no-install-recommends jq curl && \
    HOME=/home/pel /bin/bash -e -c "$(curl -fsSL https://hub.platform.engineering/get/setup.sh)" -- install --yes <plugin-name> && \
    apt-get purge -y --auto-remove jq curl && \
    rm -rf /var/lib/apt/lists/* && \
    /opt/pel/bin/formae clean --all

RUN chown -R pel:pel /opt/pel

USER pel
WORKDIR /home/pel

Replace <plugin-name> with the plugin you want. Add more plugins to the same install invocation by space-separating them.

The chown -R pel:pel /opt/pel is required. The plugin install runs as root and can leave root-owned files under /opt/pel. The agent runs as pel and refuses to start when its install tree is root-owned, and the image has no sudo, so restore ownership at build time.

Build and verify locally

docker build -t formae-extended:test .
docker run --rm formae-extended:test /opt/pel/bin/formae plugin list

The plugin you added should appear alongside the standard set. To confirm the agent loads it at startup:

docker run --rm -p 49684:49684 formae-extended:test
# In another shell:
docker logs <container> 2>&1 | grep "Plugin registered"

Look for a Plugin registered: namespace=<UPPERCASE> line for the plugin you added.

Deploy the derived image

Each install path pulls the agent image from its own registry. Push the derived image to the registry your deployment reads from, then point the deployment at it instead of ghcr.io/.../formae:latest.

AWS (Bootstrap): push to ECR, then pass the derived image as --formae-image when you install or upgrade the agent.
Azure Container Instances: push to ACR (or any registry the ACI managed identity can read), then set --image on the Azure deploy.
GCP Cloud Run: push to an Artifact Registry repository in the same project, then set --image on the GCP deploy.
Kubernetes / Helm: push to any registry the cluster can pull from, then override the chart image with --set image.repository=<your-registry>/formae-extended --set image.tag=<your-tag> on the Helm install.

Verify the running agent

formae plugin list reads the local /opt/pel tree only; there is no remote API for plugin inspection. To verify a cloud-deployed agent loaded the plugin, exec into the running container or read its startup logs.

Deployment	Verification
AWS ECS	`aws ecs execute-command --cluster <c> --task <t> --container formae-agent --interactive --command /bin/sh`, then `formae plugin list` (the service needs `--enable-execute-command`)
Azure Container Instances	`az container exec --resource-group <rg> --name <name> --exec-command /bin/sh`, then `formae plugin list`
GCP Cloud Run	No interactive exec; use `gcloud logging read` and look for the `Plugin registered` line at startup
Kubernetes	`kubectl exec deploy/<release-name> -- formae plugin list`

Known constraints

The formae CLI talks only to an agent on the same version. Whoever runs the CLI against a derived-image deployment must run the version the image ships. Update the local CLI with formae update <version>.
BASE_VERSION pins the image tag, not the agent binary: a :0.87.1 image can ship a slightly newer binary because the base resolves the version at build time. To pin the binary deterministically, add an explicit setup.sh install --yes formae@<exact-version> step before the plugin install.

Get started

Guides

Concepts

Reference

Extend the agent image

Dockerfile pattern

Build and verify locally

Deploy the derived image

Verify the running agent

Known constraints

​Dockerfile pattern

​Build and verify locally

​Deploy the derived image

​Verify the running agent

​Known constraints

Dockerfile pattern

Build and verify locally

Deploy the derived image

Verify the running agent

Known constraints