Configuration

formae is configured using a Pkl configuration file that controls agent behavior, datastore settings, discovery, synchronization, logging, and observability.

Configuration format

The configuration file uses Pkl syntax and amends the base formae:/Config.pkl schema, which provides validation and defaults for all settings.

Default configuration

Configuration lives under your formae config directory, $HOME/.config/formae/ by default (it also honors $XDG_CONFIG_HOME and $FORMAE_CONFIG_DIR). Each configuration is stored as a named profile at profiles/<name>.pkl, and the active one is recorded in a plain-text active file alongside them. The first time you run a command that needs configuration, formae creates a ready-to-use default profile pointed at a local agent (any pre-existing configuration is migrated into this layout automatically). Use the formae profile command to create, switch between, and compare profiles, or --profile <name> to target one for a single command. Everything below describes the contents of a single profile file. A minimal profile file looks like:

amends "formae:/Config.pkl"

agent {
}

cli {
}

Complete configuration reference

Below is a complete configuration showing all available options with their defaults:

amends "formae:/Config.pkl"

agent {
    server {
        nodename = "formae"
        hostname = "localhost"
        port = 49684
        secret = "secret"
        tlsCert = null
        tlsKey = null
    }

    datastore {
        datastoreType = "sqlite"
        sqlite {
            filePath = "~/.pel/formae/data/formae.db"
        }
        postgres {
            host = "localhost"
            port = 5432
            user = "postgres"
            password = "admin"
            database = ""
            schema = ""
            connectionParams = ""
        }
        auroraDataAPI {
            clusterArn = ""
            secretArn = ""
            database = ""
            region = ""
        }
        mssql {
            host = ""
            port = 1433
            database = ""
            authMode = "sql"
            user = ""
            password = ""
            encrypt = true
            trustServerCertificate = false
            connectionParams = ""
            maxOpenConns = 4
            connMaxLifetime = 1.h
        }
    }

    synchronization {
        enabled = true
        interval = 5.min
    }

    discovery {
        enabled = true
        labelTagKeys = new Listing {
            "Name"
        }
        interval = 10.min
        resourceTypesToDiscover = new Listing { }
    }

    logging {
        filePath = "~/.pel/formae/log/formae.log"
        fileLogLevel = "debug"
        consoleLogLevel = "info"
    }

    oTel {
        enabled = false
        serviceName = "formae-agent"
        otlp {
            enabled = true
            endpoint = "http://localhost:4317"
            protocol = "grpc"
            insecure = true
            temporality = "delta"
        }
        prometheus {
            enabled = true
        }
    }

    retry {
        statusCheckInterval = 20.s
        maxRetries = 9
        retryDelay = 10.s
    }
}

cli {
    api {
        url = "http://localhost"
        port = 49684
    }
    theme = "quiet"
    appearance = "auto"
}

pluginDir = "~/.pel/formae/plugins"

artifacts {
    repositories {
        new {
            uri = "https://hub.platform.engineering/repos/platform.engineering/pel#stable"
            type = "binary"
        }
        new {
            uri = "https://hub.platform.engineering/repos/platform.engineering/community#stable"
            type = "formae-plugin"
        }
    }
}

Several optional sections have no defaults and are omitted above: Authentication (agent.auth, cli.auth), Resource plugins (agent.resourcePlugins), and Network (top-level network). See the respective sections below to configure them.

Configuration reference

Server settings

Controls the agent’s network configuration and cluster identity. Essential for multi-agent deployments.

Property	Type	Default	Description
`nodename`	String	`"formae"`	Unique identifier for this agent in the cluster
`hostname`	String	`"localhost"`	Network interface where the agent listens for incoming connections
`port`	Number	`49684`	Port number for the agent API
`secret`	String	`"secret"`	Cluster-wide authentication token for secure agent communication
`tlsCert`	String?	`null`	Path to TLS certificate file for secure connections
`tlsKey`	String?	`null`	Path to TLS private key file for secure connections

Datastore

Choose between SQLite (default, suitable for single-agent), PostgreSQL (recommended for production with high availability requirements), Aurora Data API (for AWS deployments), or Microsoft SQL Server (for Azure deployments, including Azure SQL Database).

Property	Type	Default	Description
`datastoreType`	String	`"sqlite"`	Type of datastore to use: `"sqlite"`, `"postgres"`, `"auroradataapi"`, or `"mssql"`

SQLite configuration

Property	Type	Default	Description
`filePath`	String	`"~/.pel/formae/data/formae.db"`	Path to the SQLite database file

PostgreSQL configuration

Property	Type	Default	Description
`host`	String	`"localhost"`	PostgreSQL server hostname
`port`	Number	`5432`	PostgreSQL server port
`user`	String	`"postgres"`	Database user for authentication
`password`	String	`"admin"`	Database password for authentication
`database`	String	`""`	Database name to connect to
`schema`	String	`""`	PostgreSQL schema to use
`connectionParams`	String	`""`	Additional connection parameters

Aurora Data API configuration Use Aurora Data API for data access via AWS RDS Data API.

Property	Type	Default	Description
`clusterArn`	String	`""`	ARN of the Aurora Serverless cluster
`secretArn`	String	`""`	ARN of the Secrets Manager secret containing database credentials
`database`	String	`""`	Database name to connect to
`region`	String	`""`	AWS region where the cluster is located (uses default region if empty)

Microsoft SQL Server configuration Use Microsoft SQL Server for self-hosted SQL Server instances or Azure SQL Database.

Property	Type	Default	Description
`host`	String	`""`	SQL Server hostname (for Azure SQL Database, the fully qualified server name, e.g. `myserver.database.windows.net`)
`port`	Number	`1433`	SQL Server port
`database`	String	`""`	Database name to connect to
`authMode`	String	`"sql"`	Authentication mode: `"sql"` (username and password) or `"workload-identity"` (Azure AD workload identity)
`user`	String	`""`	Database user for SQL authentication
`password`	String	`""`	Database password for SQL authentication
`encrypt`	Boolean	`true`	Encrypt the connection with TLS
`trustServerCertificate`	Boolean	`false`	Accept the server certificate without validation (use only for development and testing)
`connectionParams`	String	`""`	Additional connection parameters
`maxOpenConns`	Number	`4`	Maximum number of open connections in the pool
`connMaxLifetime`	Duration	`1.h`	Maximum lifetime of a pooled connection

With authMode = "workload-identity", the agent authenticates using the Azure AD workload identity available in its runtime environment, and the user and password properties are ignored. This is the recommended mode for Azure SQL Database when the agent runs on Azure infrastructure with a managed identity.

Synchronization

Enable synchronization of managed resources. When enabled, formae periodically checks if resources have been modified outside of the tool.

Property	Type	Default	Description
`enabled`	Boolean	`true`	Enable synchronization of managed resources
`interval`	Duration	`5.min`	How frequently to check for external changes

Discovery

Automatically finds and catalogs infrastructure resources not yet under formae management. Useful for onboarding existing infrastructure. Discovery scans targets that have been marked as discoverable = true in your forma files. See the discovery documentation for details on configuring discoverable targets.

Property	Type	Default	Description
`enabled`	Boolean	`true`	Enable automatic resource discovery
`labelTagKeys`	List<String>	`["Name"]`	Tag keys to use when building resource labels (concatenated with dashes)
`interval`	Duration	`10.min`	How frequently to run discovery scans
`resourceTypesToDiscover`	List<String>	`[]`	Specific resource types to discover (empty list discovers all supported types)

Logging

Configure log output levels and file locations.

Keep the file log level at debug for troubleshooting support.

Property	Type	Default	Description
`filePath`	String	`"~/.pel/formae/log/formae.log"`	Path to the log file
`fileLogLevel`	String	`"debug"`	Log level for file output: `"debug"`, `"info"`, `"warn"`, `"error"`
`consoleLogLevel`	String	`"info"`	Log level for console output: `"debug"`, `"info"`, `"warn"`, `"error"`

OpenTelemetry

Enable telemetry export to your observability platform. When enabled, metrics, logs, and traces are pushed via OTLP.

Property	Type	Default	Description
`enabled`	Boolean	`false`	Enable OpenTelemetry integration
`serviceName`	String	`"formae-agent"`	Service name for telemetry identification

OTLP configuration

Property	Type	Default	Description
`enabled`	Boolean	`true`	Whether to enable OTLP push export for traces, metrics, and logs
`endpoint`	String	`"http://localhost:4317"`	OTLP collector endpoint URL
`protocol`	String	`"grpc"`	Protocol to use: `"grpc"` or `"http"`
`insecure`	Boolean	`true`	Whether to use insecure connections (disable TLS)
`temporality`	String	`"delta"`	Metric temporality: `"delta"` (OTel-native) or `"cumulative"` (for Prometheus/Mimir backends without delta support)

Prometheus configuration

Property	Type	Default	Description
`enabled`	Boolean	`true`	Enable Prometheus `/metrics` endpoint for pull-based scraping

Retry

Control how formae handles transient failures during resource operations. These values are the agent-wide defaults and can be overridden per plugin in Resource plugins.

Property	Type	Default	Description
`statusCheckInterval`	Duration	`20.s`	How frequently to check the status of a resource operation
`maxRetries`	Number	`9`	Maximum number of retries for a recoverable failed operation
`retryDelay`	Duration	`10.s`	How long to wait before retrying a failed operation

Resource plugins

agent.resourcePlugins is a list of per-plugin configuration blocks that override defaults published by each plugin. Each installed plugin ships its own typed configuration that you import through the plugins:/ scheme. Any plugin that is not listed uses its built-in defaults. Available overrides on every resource plugin:

Property	Type	Description
`enabled`	Boolean	Set to `false` to disable the plugin. When disabled no other fields apply. Default: `true`.
`rateLimit`	RateLimitConfig?	Cap the request rate this plugin issues to its provider. `maxRequestsPerSecondForNamespace` is the per-target cap.
`retry`	RetryConfig?	Override the agent-wide retry settings for this plugin.
`resourceTypesToDiscover`	List<String>?	Restrict which resource types this plugin reports during discovery. An empty/absent value means “all supported types”.
`discoveryFilters`	List<MatchFilter>?	Exclude specific discovered resources by matching on properties (for example, skipping resources that carry a Kubernetes-owner tag).
`labelConfig`	LabelConfig?	Customize how human-readable labels are generated for discovered resources. `defaultQuery` is a JSONPath query; `resourceOverrides` sets per-resource-type queries that win over the default.

Plugins may also expose plugin-specific fields defined in their own schema/Config.pkl. These appear alongside the fields above on the same configuration block.

Disabling a plugin

Use enabled = false to stop the agent from loading a plugin. No other options apply in this case.

amends "formae:/Config.pkl"

import "plugins:/Azure.pkl" as Azure

agent {
    resourcePlugins {
        new Azure.PluginConfig {
            enabled = false
        }
    }
}

Tuning an installed plugin

This example uses the SFTP plugin because it exposes plugin-specific fields (defaultTimeoutSeconds, defaultFilePermissions) in addition to the common overrides.

amends "formae:/Config.pkl"

import "plugins:/Sftp.pkl" as Sftp

agent {
    resourcePlugins {
        new Sftp.PluginConfig {
            // Common overrides
            rateLimit {
                maxRequestsPerSecondForNamespace = 5
            }
            retry {
                maxRetries = 3
                retryDelay = 30.s
            }

            // Plugin-specific fields defined by the SFTP plugin
            defaultTimeoutSeconds = 60
            defaultFilePermissions = "0600"
        }
    }
}

You can combine multiple plugin blocks under a single resourcePlugins { ... } listing. The type field is automatically set by each plugin’s wrapper, so you only need to fill in the overrides you care about.

labelConfig

labelConfig customizes how human-readable labels are generated for resources discovered by this plugin. The query is a JSONPath expression evaluated against the resource’s properties. Each plugin ships a sensible default (for example, the AWS plugin uses the Name tag, $.Tags[?(@.Key=='Name')].Value). Override per resource type when the plugin’s default doesn’t suit your environment, or set defaultQuery to change the rule for every type:

amends "formae:/Config.pkl"

import "plugins:/Aws.pkl" as Aws

agent {
    resourcePlugins {
        new Aws.PluginConfig {
            labelConfig {
                resourceOverrides {
                    ["AWS::EC2::Instance"] = "$.Tags[?(@.Key=='env')].Value"
                }
            }
        }
    }
}

When the query returns nothing, formae falls back to the resource’s provider identifier as the label. See Label: Labels for discovered resources for the full resolution order and collision behavior.

CLI

Configure how the CLI connects to the agent API, and how its output is themed. See Authentication for cli.auth.

Property	Type	Default	Description
`api.url`	String	`"http://localhost"`	Base URL for the agent API
`api.port`	Number	`49684`	Port number for the agent API
`theme`	String	`"quiet"`	CLI theme: a built-in (`"quiet"`, `"rich"`, `"colorblind"`) or the filename of a theme in `~/.config/formae/themes/`. Unknown names warn and fall back to `quiet`. See CLI themes.
`appearance`	String	`"auto"`	Which color variant to use: `"light"`, `"dark"`, or `"auto"` (detect the terminal background). Orthogonal to `theme`. The `FORMAE_APPEARANCE` environment variable overrides it.

Authentication

Authentication is configured separately for the agent and CLI. The agent.auth block controls server-side validation; the cli.auth block provides client-side credentials. Both fields are optional. If unset, the agent serves unauthenticated requests. Each auth plugin ships its own typed configuration that you import through the plugins:/ scheme, the same pattern used for Resource plugins. The example below uses the auth-basic plugin, which is the default HTTP Basic Authentication option.

amends "formae:/Config.pkl"

import "plugins:/AuthBasic.pkl" as AuthBasic

agent {
    auth = new AuthBasic.AgentConfig {
        authorizedUsers {
            new AuthBasic.AuthorizedUser {
                username = "alice"
                // bcrypt hash, generate with:
                //   htpasswd -bnBC 10 "" yourPassword | tr -d ':'
                password = "$2y$10$ki1wCrM94EViuTv0dRNEVuP3ujj2/uu2Zh8/FyFvExjZyrsdtr1SS"
            }
        }
    }
}

cli {
    auth = new AuthBasic.CliConfig {
        username = "alice"
        password = "mySecretPass"
    }
}

See Security and networking for more detail on the auth-basic setup.

Network

Top-level network configuration. The type field selects the network plugin.

Property	Type	Default	Description
`network.type`	String	none	Network plugin type (e.g. `"tailscale"`)
`network.tailscale`	TailscaleConfig?	`null`	Tailscale-specific configuration

See Tailscale for setup instructions.

Plugin directory

Top-level setting for where formae discovers installed plugins.

Property	Type	Default	Description
`pluginDir`	String	`"~/.pel/formae/plugins"`	Directory where installed plugins live. Can also be set via the `FORMAE_PLUGIN_DIR` environment variable.

Artifact repositories

Top-level artifacts block configures the orbital repositories formae consults to install and update its binary, plugins, and tooling. Both the agent and the CLI share this configuration; formae plugin install, formae update, and formae plugin upgrade all resolve packages against the listed repositories.

Property	Type	Default	Description
`artifacts.repositories`	`Listing<Repository>`	`pel` (binary) and `community` (formae-plugin) on `hub.platform.engineering` at the `stable` channel	List of orbital repositories to consult for packages. The defaults cover both binary and plugin distribution; only override when running against a private or custom hub.

Each entry in artifacts.repositories is a Repository with two fields:

Property	Type	Description
`uri`	String	Orbital repository URI; the optional `#channel` fragment selects the release channel (typically `stable` or `dev`).
`type`	`"binary"` \| `"formae-plugin"`	Discriminator. `binary` repos serve the formae binary and tooling (consulted by `formae update`); `formae-plugin` repos serve plugins (consulted by `formae plugin install / upgrade`).

The default value is equivalent to:

artifacts {
    repositories {
        new {
            uri = "https://hub.platform.engineering/repos/platform.engineering/pel#stable"
            type = "binary"
        }
        new {
            uri = "https://hub.platform.engineering/repos/platform.engineering/community#stable"
            type = "formae-plugin"
        }
    }
}

A typical override that points at a private hub mirroring the same shape:

artifacts {
    repositories {
        new {
            uri = "https://hub.example.com/repos/example.com/pel#stable"
            type = "binary"
        }
        new {
            uri = "https://hub.example.com/repos/example.com/community#stable"
            type = "formae-plugin"
        }
    }
}

Deprecated flat fields

Earlier releases configured a single repository via flat artifacts.url, artifacts.username, and artifacts.password fields. Those fields are still accepted for backwards compatibility but emit deprecation warnings on agent startup, and they cover only the binary repository: plugin installation requires the new repositories listing. Migrate by replacing:

artifacts {
    url = "https://hub.platform.engineering/repos/platform.engineering/pel#stable"
}

with the explicit listing shown above. The username and password fields have no like-for-like replacement in 0.85; per-repository credentials will be reintroduced in a later release.

Deprecated `plugins` block

Earlier releases configured authentication, network access, and the plugin directory under a single top-level plugins { ... } block. That block is still accepted for backwards compatibility but emits deprecation warnings at startup. Migrate as follows:

Old location	New location
`plugins.authentication`	`agent.auth` + `cli.auth`
`plugins.network`	top-level `network`
`plugins.pluginDir`	top-level `pluginDir`

Get started

Guides

Concepts

Reference

Configuration format

Default configuration

Complete configuration reference

Configuration reference

Server settings

Datastore

Synchronization

Discovery

Logging

OpenTelemetry

Retry

Resource plugins

Disabling a plugin

Tuning an installed plugin

labelConfig

CLI

Authentication

Network

Plugin directory

Artifact repositories

Deprecated flat fields

Deprecated `plugins` block

​Configuration format

​Default configuration

​Complete configuration reference

​Configuration reference

​Server settings

​Datastore

​Synchronization

​Discovery

​Logging

​OpenTelemetry

​Retry

​Resource plugins

​Disabling a plugin

​Tuning an installed plugin

​labelConfig

​CLI

​Authentication

​Network

​Plugin directory

​Artifact repositories

​Deprecated flat fields

​Deprecated plugins block

Configuration format

Default configuration

Complete configuration reference

Configuration reference

Server settings

Datastore

Synchronization

Discovery

Logging

OpenTelemetry

Retry

Resource plugins

Disabling a plugin

Tuning an installed plugin

labelConfig

CLI

Authentication

Network

Plugin directory

Artifact repositories

Deprecated flat fields

Deprecated `plugins` block