> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/architecture/agent-application-settings.md).

# Agent application settings

Additional settings available for the cross platform Agents.

When setting up a Frends Agent, there are configuration files and options available to adjust the Agent's settings. This is especially useful and important for containerized deployments, when Agents may be deployed without manual intervention.

## Settings files

The Agent application reads its settings from a number of files, and the settings can also be given to the Agent as environment variables. This is especially useful and important for containerized deployments, when Agents may be deployed without manual intervention.

The Agent reads these files:

1. `appsettings.json`
2. `appsettings.production.json`
3. `secrets/appsettings.secrets.json`

The configuration in these files cascade in priority, with latter files overriding settings from earlier ones.

The files `appsettings.json` and `secrets/appsettings.secrets.json` are overwritten during installation, so lasting changes shouldn't be made there and you should make your changes to the `appsettings.production.json` file instead. The production file has to be created manually, into the same folder as the `appsettings.json` file.

All changes to the files are applied to the Agent after restarting the Agent, unless a setting description says otherwise. Reinstallation is not necessary to apply the settings.

### Reading the setting descriptions

Most of these settings are pre-configured correctly when you download the configuration from the Frends Control Panel. However, you can edit them manually in the `appsettings.json` file. Each description below explains what the setting is used for and where its value comes from.

Setting names are not case-sensitive. Settings that contain other settings, such as `HttpLoggingOptions`, are written as nested JSON objects in the files. In environment variables the levels are separated with a double underscore, as in `Storage__S3ObjectStorage__BucketPrefix`.

Some descriptions are marked with SA or HA. SA means a single Agent in the Agent Group, and HA means high availability, with multiple Agents in the Agent Group.

## Identity and connection

These settings tell the Agent who it is and how it connects to the Frends Control Panel and the message bus. They are required for the Agent to run, and they are provided by the Frends Control Panel when you download the installation configuration.

#### AgentGroupName

Name of the Agent Group where the Agent runs.

#### AgentName

Name of the Agent.

#### EnvironmentName

Name of the Environment where the Agent runs.

#### BootstrapKey

A one-time key that an Agent running on Azure Service Bus uses to get its Azure Service Bus access tokens from the Frends Control Panel. The key is part of the configuration you download for the Agent, so you do not need to create or edit it by hand.

At every startup the Agent redeems the key for the tokens it needs and stores the tokens locally. A key can be used once, and it keeps working for 60 minutes after its first use so that a failed startup can be retried. Downloading or viewing the configuration again replaces the key, and an Agent that has already stored its tokens keeps working with them.

Agent Groups in Kubernetes Deployment or Kubernetes StatefulSet registration mode share one reusable key instead, and the names of Agents in these Agent Groups cannot contain `_`.

An Agent without a key stops with an error that says to download its configuration again. The same happens when the Agent cannot reach the Frends Control Panel on its first startup. Agents on RabbitMQ do not use this key.

{% hint style="info" %}
This setting is introduced in Frends 6.3.3. When updating from 6.3.2 or earlier, download each Agent together with its configuration, or the Kubernetes deployment files, again. Do not give an Agent of an earlier version a newly downloaded configuration, because it cannot use the key.
{% endhint %}

#### AzureServiceBusSasTokenConfiguration

Configuration for the Azure Service Bus connection. Not required if `RabbitMqConnectionString` is configured.

Contains properties:

* **Endpoint**: Azure Service Bus namespace, e.g. foobar.windows.net (string)
* **UseAmqpWebSockets**: Whether to use AMQP WebSockets to connect to Azure Service Bus for communications (bool)
* **SasTokensPerQueueIdentifier**: SAS tokens for each queue, if required (key-value pairs of string: string). Configurations downloaded for Frends 6.3.2 and earlier contain the tokens here. Later configurations contain a `BootstrapKey` instead.

#### RabbitMqConnectionString

Connection string for the RabbitMQ connection.

Not required if an Azure Service Bus connection has been configured.

#### InstallationIdentifier (*SQLite*)

This value needs to be unique for all Agents running on the same machine. It can be ignored if only one Agent is running on the machine.

## State and databases

These settings decide where the Agent keeps its state, such as the state of Schedule and FileWatch Triggers.

If the Agent Group has multiple Frends Agents, either `AgentDatabaseConnectionString` or `SharedStateStore` has to be set to be able to run Schedule and FileWatch Triggers. If neither is set, the Agent State is stored in SQLite and not shared between Agents.

#### AgentDatabaseConnectionString (*optional, SQL Server, HA*)

This value is configured in the Agent Group view in the Frends Control Panel, and all Agents in the Agent Group have to use the same connection string.

#### DataDirectory (*optional, containers, SQLite, SA*)

This determines where the SQLite databases are stored for the Agent.

For a single Agent running in a container, this needs to be set to a location outside the container itself to store Schedule and FileWatch Trigger states.

#### SharedStateStore

Settings for Shared State configuration.

Properties:

* **ConnectionString**: A database connection string (string)

#### AdditionalSqLiteConnectionStringOptions (*SQLite*)

Extra options that are added to the connection string of the Agent's SQLite databases. The value is a semicolon-separated list of `key=value` pairs.

Default: `journal_mode=WAL;busy_timeout=5000;`

The busy timeout is 0 when the option is not given.

## Storage locations

These settings tell the Agent where to read and write Process packages, step data, large messages and network shares. Where a setting takes a storage location, it can be an URL for an Azure blob container (with the SAS token) or a Windows file URI (`file://`).

#### LogStepStoreUri

The location where the Frends Agent logs Process instance steps.

#### LargeMessageStoreUri

Messages that do not fit in the message bus are transferred via this location.

#### ProcessHostPackageStoreUri

The location from where the Frends Agent downloads the Processes built in the Frends Control Panel.

#### Storage\_\_S3ObjectStorage\_\_BucketPrefix

Configurable prefix for S3 bucket names in S3-compatible object stores. In S3-compatible object stores, bucket names must be **globally unique across the entire system**. This may cause conflicts when multiple Tenants use the same Agent Group names.

When set, bucket names become `{prefix}-steps-{agentgroup}` and `{prefix}-lms-{agentgroup}`. When not set, behavior remains unchanged (`steps-{agentgroup}` and `lms-{agentgroup}`) for backward compatibility.

{% hint style="warning" %}
Recommended to be set only for new Tenants. Changing this setting for an existing Tenant causes loss of step data.
{% endhint %}

The value may contain letters, numbers, and dashes. Dashes cannot be leading or trailing. Maximum length is 6 characters.

#### EnforceServerCertificateForPreSignedUri

If set to `true`, the Agent requires a valid and trusted TLS server certificate when calling the pre-signed URI provider used with S3 blob storage.

Default is `false`.

{% hint style="info" %}
This setting is introduced in Frends 6.3.1.
{% endhint %}

#### MappedDrivesConfiguration

The list of network shares that the Agent mounts when it starts.

Each entry can contain the property:

* **IgnoreErrorOnStartup**: If `true`, the Agent starts even when the network share cannot be mounted. If `false`, the Agent fails to start when a share cannot be mounted. Default is `false`.

{% hint style="info" %}
The `IgnoreErrorOnStartup` property is introduced in Frends 6.3.1.
{% endhint %}

## Listeners, certificates and client authentication

These settings decide which ports the Agent listens to, which certificate it presents, and how it treats callers and proxies in front of it.

#### HttpPorts (json) or HttpPortsString (environment variable)

If this is set, the Frends Agent attempts to start listening for HTTP traffic on the configured ports.

`HttpPorts` expects a JSON array of integers, e.g. `[ 9996, 9997 ]`. `HttpPortsString` expects a string where the ports are comma separated, e.g. `"9996, 9997"`.

#### HttpsPorts (json) or HttpsPortsString (environment variable)

If this is set, the Frends Agent attempts to start listening for HTTPS traffic on the configured ports.

`HttpsPorts` expects a JSON array of integers, e.g. `[ 443, 9999 ]`. `HttpsPortsString` expects a string where the ports are comma separated, e.g. `"443, 9999"`.

#### HttpStatusinfoPort

If you wish to host the status info page on a separate HTTP port, you can configure it with this option.

The value should be an integer, e.g. `"HttpStatusinfoPort": 9901`.

#### HealthCheckApiKey

If left empty, the HTTP(S) health check endpoints (`/FrendsStatusInfo` and `/FrendsStatusInfoLiveness`) are accessible without any authentication. *Leave this empty if you have Gateway Agents in the same Agent Group.*

If set, the health check endpoints require the API key set here to be sent in the `health-check-api-key` header.

#### CertificateThumbprintOrPath

Specifies the certificate the Agent uses to secure its API and HTTP(S) endpoints. Accepts either a **certificate thumbprint** or a **full file path** to a `.pfx` file.

* **Thumbprint**: Provide a hex thumbprint string, e.g. `A1B2C3D4E5F6...`. The certificate must be pre-installed on the machine. The Agent searches the `My` store in `CurrentUser` by default. Use the `CertificateStore` setting to switch to `LocalMachine`.
* **File path**: Provide the full path to a `.pfx` file, e.g. `/app/secrets/cert.pfx`. The Agent must have read access to the file. If the certificate is password-protected, also set `CertificatePassword`. Updating the Frends Agent overwrites this setting, unless the new Frends Agent application settings file is edited accordingly.
* **Empty or not set**: The Agent auto-generates a self-signed certificate. This is not recommended for production, especially in containers where the certificate regenerates on each new instance.

See [Configuring SSL Certificates for Frends Agent](https://docs.frends.com/guides/setup-and-installation/configuring-ssl-certificates-for-frends-agent) for more details about installing and configuring the certificates.

#### CertificateStore

The name of the certificate store where the specified certificate is located.

Default: `CurrentUser`

Other supported values: `LocalMachine`

#### CertificatePassword

This setting is used if a certificate for HTTPS is provided with a file path.

#### EnableClientCertificateValidation

Controls whether the Agent requests a client certificate during the HTTPS TLS handshake.

* `null` or not set: request an optional client certificate only when at least one HTTP Trigger uses Certificate authorization, otherwise do not request one
* `true`: always request a client certificate
* `false`: never request a client certificate

Default is `null`.

Changes take effect for new connections without restarting the Agent.

{% hint style="info" %}
The `null` value and its behavior as the default are introduced in Frends 6.3.1. Earlier versions accept only `true` and `false`.
{% endhint %}

#### ForwardedHeaders

Controls which proxies the Agent trusts to tell it the host name and protocol that callers used. The Agent reads the `X-Forwarded-Host` and `X-Forwarded-Proto` headers from trusted proxies when it builds the URLs it returns for OpenAPI documents, the MCP Trigger and its OAuth discovery. The RFC 7239 `Forwarded` header is not read.

Proxies on loopback and, by default, private networks are trusted, so you only need to change these settings when your proxy uses a public address.

Contains properties:

* **ApplyToAllRequests**: Whether the trusted forwarded headers are honoured on every request instead of only for OpenAPI documents, the MCP Trigger and its OAuth discovery. Default is `false`, so HTTP Trigger requests are not affected unless you set it to `true`.
* **TrustPrivateNetworks**: Whether proxies in private networks (RFC 1918 and `fc00::/7`) are trusted in addition to loopback. Default is `true`. If `false`, only loopback and the proxies and networks listed in this section are trusted.
* **KnownProxies**: Additional trusted proxy IP addresses, as a JSON array of strings, e.g. `["203.0.113.10"]`.
* **KnownNetworks**: Additional trusted proxy networks in CIDR notation, as a JSON array of strings, e.g. `["203.0.113.0/24"]`.
* **AllowedHosts**: Host names accepted on requests where forwarded headers are honoured, e.g. `["api.example.com", "*.example.com"]`. The host is checked against both the `X-Forwarded-Host` and the `Host` header, and a request with any other host gets a 400 response. If empty, any host is accepted.

{% hint style="info" %}
This setting is introduced in Frends 6.4.
{% endhint %}

#### Kestrel

Settings of the web server that the Agent uses to listen for HTTP and HTTPS traffic.

Contains the property:

* **Limits:MaxRequestBodySize**: The maximum size of a request body in bytes. Requests with a larger body are rejected. The shipped value is the maximum 64-bit integer, 9223372036854775807, so there is effectively no limit.

## Logging and masking

These settings control what the Agent writes to its HTTP log and Process logs, and which values it hides from them.

#### HttpLoggingOptions (json)

A set of options related to how HTTP connections to APIs are logged.

Possible options include:

* **BufferDelayInMilliseconds**: Length of buffering for logs. Default is 1000
* **Disable**: Disable HTTP logging
* **HeadersToOmit**: List of headers to not save in logs. The specified header values are displayed as **<\<Omitted>>** in the Frends Control Panel. Provided as a JSON array of strings, default value is `["Authorization","Cookie","Set-Cookie","X-Api-Key","X-Auth-Token","Proxy-Authorization"]`
* **UnauthenticatedRequestsPerEndpointPerMinute**: How many requests that fail authentication or match no endpoint are logged in full per minute, for each endpoint, declared HTTP method and status code. Default is 10
* **UnauthenticatedRequestsPerAgentPerMinute**: How many such requests are logged in full per minute in total on the Agent. Default is 100

Requests over the two limits are summarised as one HTTP log entry per endpoint, declared HTTP method and status code each minute, with the number of requests in the path of the entry. If you count rejected requests from the HTTP log, count the summary entries too.

{% hint style="info" %}
The two limits are introduced in Frends 6.4.
{% endhint %}

#### TriggerHeadersToMask

List of names whose values are masked in Process logs when they appear in HTTP Trigger and API Trigger requests. The names are matched, without regard to case, against both request headers and query parameters.

Default: `Authorization`, `Cookie`, `X-Api-Key`, `X-ApiKey`, `X-Auth-Token` and `Proxy-Authorization`.

Listing `Cookie` masks the value of every cookie of the request. The header or query parameter that an API Policy reads its API key from is always masked, whether or not it is on the list.

The masking applies to a Process once a new version of it has been saved and deployed. Process versions saved before the update keep logging as before.

{% hint style="info" %}
This setting was introduced in Frends 6.4.
{% endhint %}

#### FileSystemInstanceLoggingPath

If set, the Agent logs Instances to a file in the specified path.

#### MaxLogFlushWaitDurationSeconds

Maximum amount of time in seconds to wait before timing out a log flush.

Default: 300

## Agent log files

The Agent writes its own log with the standard .NET logging configuration, in the `Logging` section of the settings. Unlike the other settings, changes to the log levels are applied while the Agent is running, without a restart.

#### Logging:LogLevel

Sets the minimum log level for each log category of the Agent. The shipped default for most Frends categories, such as `Frends.Agent.Program`, `Frends.Agent.Execution` and `Frends.Messaging`, is `Information`. The categories `Microsoft.AspNetCore`, `Microsoft.Hosting.Lifetime` and `NHibernate` are set to `Warning`, and `Default` is `Information`.

The category `Frends.Process` is set to `Debug`. The log level of a Process is set per Process in the Frends Control Panel, and this value is only the minimum level of the logger. The category `ProcessExecutionService` is not a class name. It is used for the per-Process start, finish and resume messages.

#### Logging:File

Settings of the Agent's log files. The following properties apply to all of them:

* **MaxFileSize**: The maximum size of a log file in bytes. Default is 10485760 (10 MB)
* **MaxFiles**: The maximum number of log files. Default is 20
* **Files**: The list of log files. Each file has a `Path`, where `<counter>` is replaced with a running number, and a `MinLevel` setting that tells which categories are written to it

The Agent writes three files by default. `FRENDSAgentService-<counter>.log` is the main log and contains all categories except the per-Process execution messages. `FRENDSAgentServiceProcess-<counter>.log` contains only the per-Process start, finish and resume messages. `FRENDSAgentServiceErrors-<counter>.log` contains messages of level `Error` and above.

## Gateway Agents

These settings are relevant if the Frends Agent is a Gateway Agent.

#### GatewayTargetAddresses

If this setting is set, the Frends Agent is considered to be a Gateway Agent.

This should be a JSON string array with all the addresses of the targets, e.g. `["https://agent1.local:443","https://agent2.local:443"]`.

#### AllowUnsafeServerCertificateForGateway

If this setting is set, the target Frends Agents do not need to have valid SSL certificates for the Gateway to proxy traffic to the Agents.

Default is `false`.

#### TimeoutMinutesForGateway

Maximum time the Gateway waits for the response headers from the target Frends Agent, and then for each further piece of the response body. A response that keeps sending data is not cut off. If the target stops sending after its headers have been passed on, the Gateway closes the connection to the caller.

Default is 10 minutes.

## AI Connector

These settings control how the Agent calls AI services and downloads the files that AI Connector parameters refer to.

#### NativeAiSettings (json)

Configuration for the AI Connector. Contains properties:

* **FrendsAiClientTimeoutSeconds**: Timeout in seconds for calling the FrendsAi endpoint
* **FileDownloadClientTimeoutSeconds**: Timeout in seconds for the AI Connector fetching files
* **EnforceServerCertificateForNativeAiDownloads**: If `true`, the Agent enforces standard TLS server certificate validation when fetching file or image URLs referenced in Native AI chat parameters. Default is `false`, so downloads behind private or self-signed certificates keep working

Both timeouts default to 100 seconds, which is suitable in most cases.

{% hint style="info" %}
`EnforceServerCertificateForNativeAiDownloads` is introduced in Frends 6.3.1.
{% endhint %}

## Process execution and limits

These options are optional and should only be set if you know what you are doing.

#### AppDomainSetupTimeout

The timeout timespan for the initial package directory and app domain setup.

Type: [Timespan](https://learn.microsoft.com/en-us/dotnet/core/compatibility/serialization/6.0/timespan-serialization-format)

Default: 10 minutes

#### CheckInstancesForZombiesRunningLongerThanMinutes

Amount of minutes for a Process to run before it is checked for being a zombie, and terminated if it is.

Default: 900

#### HeartBeatStatusInfoDebounceDelay

Amount of time spent per received heartbeat status message to ignore other following messages in the observable sequence.

Type: [Timespan](https://learn.microsoft.com/en-us/dotnet/core/compatibility/serialization/6.0/timespan-serialization-format)

Default: 2 seconds

#### MaxConcurrentRemoteSubprocessesPerCpu

Maximum amount of concurrent Remote Subprocesses per CPU.

Default: 64

#### MaxConcurrentBlobTransfersPerCpu

Maximum amount of concurrent blob transfers per CPU core.

Default: 4

#### MaxDehydratedProcessDataSizeKb

Maximum amount of data stored by a Checkpoint shape for each Process Instance, in kilobytes.

Default: 1024

#### MaxSubprocessDepth

Maximum amount of Subprocesses a Process can start.

Default: 30

#### UseManagedNetworkingOnWindows

Enables managed networking for the SQL client on Windows Agents. Use it to prevent SqlConnectionPool resource starvation.

Default is `false`.

{% hint style="info" %}
This setting is introduced in Frends 6.3.0.
{% endhint %}

#### Shutdown

Settings for stopping the Agent.

Contains properties of type [Timespan](https://learn.microsoft.com/en-us/dotnet/core/compatibility/serialization/6.0/timespan-serialization-format):

* **Timeout**: How long the Agent waits before the host forces the shutdown. Default is 7 days (`7.00:00:00`)
* **FlushTimeReserve**: How much of the timeout is reserved for flushing logs and other finalization. Default is 10 seconds (`00:00:10`)
* **ForceStopProcessesTimeout**: The time allowed for forcefully stopping running Processes after the graceful wait expires. Default is 5 seconds (`00:00:05`)

On Linux, keep `Timeout` lower than the systemd `TimeoutStopSec` of the Agent service. Otherwise the operating system ends the Agent with a SIGKILL before the flush is complete, and execution state data can be lost. See [Tuning memory usage and recovery for Frends Agent on Linux](https://docs.frends.com/guides/setup-and-installation/tuning-memory-usage-and-recovery-for-frends-agent-on-linux) for the full setup.

## Telemetry

These settings let the Agent publish OpenTelemetry data to a separately installed and configured OpenTelemetry Collector. Put the values in `appsettings.production.json` as top-level settings, or set them as system environment variables. The Agent collects and publishes both metrics and traces by default, so all you need to set is the endpoint of the Collector.

To learn more about how to use these settings, see [How to visualize Frends telemetry with OpenTelemetry](https://docs.frends.com/guides/integration-management/how-to-visualize-frends-telemetry-with-opentelemetry).

#### OTEL\_EXPORTER\_OTLP\_ENDPOINT

The URL of the OpenTelemetry Collector receiver. If this is set, exporting OpenTelemetry data is enabled.

#### OTEL\_EXPORTER\_OTLP\_PROTOCOL

The protocol used to send the data to the endpoint, either `grpc` or `http/protobuf`. Use `http/protobuf` for cloud providers such as Grafana Cloud.

#### OTEL\_EXPORTER\_OTLP\_HEADERS

Headers sent with the data, for example for authentication. The format is `key=value`, or `key1=value1,key2=value2` for several headers.

#### OTEL\_SERVICE\_NAME

Overrides the service name that the Agent reports, including the Tenant. If empty, the Agent reports its Agent Group, its name and the Tenant.

#### Tenant

The name of the Tenant. The Frends Control Panel fills this in when the Agent configuration is generated. It is appended to the OpenTelemetry service name and exported as the `frends.tenant` resource attribute.

#### SamplingRatePercentage

The percentage of traces that are sampled, from 1 to 100. Default is 10.

#### EnableOTPLMetrics

Enables the Frends Agent to collect and publish OpenTelemetry metrics for a separately installed and configured OpenTelemetry Collector. Default is `true`, so you only need to set this to `false` to stop publishing metrics. The data is pushed to the URL set in `OTEL_EXPORTER_OTLP_ENDPOINT`.

#### EnableOTPLTracing

Enables the Frends Agent to collect and publish OpenTelemetry traces for a separately installed and configured OpenTelemetry Collector. Default is `true`, so you only need to set this to `false` to stop publishing traces. The data is pushed to the URL set in `OTEL_EXPORTER_OTLP_ENDPOINT`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/reference/architecture/agent-application-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
