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

The configuration file is located at $HOME/.config/formae/formae.conf.pkl. If no configuration file exists, formae uses default settings. The config file is not automatically created. Create one if you want to customize settings.

To create a minimal configuration file:

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 = ""
        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 = ""
        }
    }

    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 {
            endpoint = "http://localhost:4317"
            protocol = "grpc"
            insecure = true
        }
    }

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

cli {
    api {
        url = "http://localhost"
        port = 49684
    }
}

plugins {
}

---

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	""	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) or PostgreSQL (recommended for production with high availability requirements).

Property	Type	Default	Description
datastoreType	String	"sqlite"	Type of datastore to use: "sqlite" or "postgres"

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

---

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 file log level at debug for troubleshooting support.

Property	Type	Default	Description
filePath	String	"~/.pel/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 structured logging and metrics export to your observability platform. Metrics are automatically exposed on the /metrics endpoint when enabled.

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
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)

---

Retry

Control how formae handles transient failures during resource operations. Adjust these settings based on your infrastructure's reliability characteristics.

Property	Type	Default	Description
statusCheckInterval	Duration	10.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

---

CLI

Configure how the CLI connects to the agent API.

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

---

Plugins

Configure plugin-specific settings for authentication and network access. Plugin configuration is dynamic and depends on the specific plugin being used.

Property	Type	Default	Description
authentication	Dynamic?	null	Authentication configuration for plugins (plugin-specific)
network	Dynamic?	null	Network configuration for plugins (plugin-specific)