Configuration

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

Configuration File Location

The configuration file is loaded from:

$HOME/.config/formae/formae.conf.pkl

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

When you first run formae, a minimal configuration file is created:

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 = false
        scanTargets = new Listing<Target> {
            new {
                label = "us-west-2"
                config {
                    type = "AWS"
                    region = "us-west-2"
                }
            }
        }
        labelTagKeys = new Listing {
            "Name"
        }
        interval = 1.h
        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.

Property	Type	Default	Description
`enabled`	Boolean	`false`	Enable automatic resource discovery
`scanTargets`	List<Target>	`[]`	List of cloud targets to scan for resources
`labelTagKeys`	List<String>	`["Name"]`	Tag keys to use when building resource labels (concatenated with dashes)
`interval`	Duration	`1.h`	How frequently to run discovery scans
`resourceTypesToDiscover`	List<String>	`[]`	Specific resource types to discover (empty list discovers all supported types)

Target Configuration:

Each target in scanTargets requires a label and a provider-specific config section. The structure varies by cloud provider.

AWS Target Example:

Property	Type	Description
`label`	String	User-friendly label for this target
`config.type`	String	Must be `"AWS"` for AWS targets
`config.region`	String	AWS region to scan (e.g., `"us-west-2"`)

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)