Docker installation

Prerequisites

The formae CLI must be installed on your local machine to interact with the agent. See Local installation.

The formae agent is available as a container image:

ghcr.io/platform-engineering-labs/formae

Supported architectures: linux/amd64, linux/arm64.

Run with Docker

docker run -d -p 49684:49684 ghcr.io/platform-engineering-labs/formae:latest

The agent API is available on port 49684.

Run a specific version

docker run -d -p 49684:49684 ghcr.io/platform-engineering-labs/formae:0.82.0

Custom configuration

Mount a custom config file:

docker run -d -p 49684:49684 \
  -v /path/to/formae.conf.pkl:/config/formae.conf.pkl:ro \
  ghcr.io/platform-engineering-labs/formae:latest \
  formae agent start --config /config/formae.conf.pkl

See the Configuration docs for available options.

Applying formas

The formae CLI runs on your local machine. It evaluates your Pkl files locally and sends the result to the agent API — no files need to be loaded into the container.

The CLI connects to http://localhost:49684 by default, which matches the published port above. No additional configuration is needed when running Docker locally.

With the agent running, apply a forma from your machine:

formae apply --mode reconcile your-forma.pkl

If your agent is running on a remote host, update the CLI's agent URL in ~/.config/formae/formae.conf.pkl:

amends "formae:/Config.pkl"

cli {
    api {
        url = "http://<remote-host>"
        port = 49684
    }
}

Next steps

Head to the Quick start or see the Configuration docs for available options.