> 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/guides/setup-and-installation/tuning-memory-usage-and-recovery-for-frends-agent-on-linux.md). # Tuning memory usage & recovery for Frends Agent on Linux Optimizing Frends Agent's memory usage allows more stable execution and easier recovery. This article explains how to tune the memory and performance of a Frends Agent running on a Linux host using standard `systemd` and `systemctl` features. While these capabilities are built into the Linux operating system, they are recommended for maintaining Agent stability and protecting host resources. Frends provides these configurations by default starting with version 6.3.1, but they can be manually implemented for earlier Agent versions. ## Prerequisites The Frends Agent must be installed on a Linux machine to be able to utilise these settings. You must have `sudo` access to edit service files and restart the service, and a basic understanding of the Linux command line is helpful. To fully utilize the optimizations, the Linux machine is required to have swap enabled. ## Service Configuration Options The Frends Agent service is managed by `systemd`, which provides native controls for resource allocation and service health. These settings allow the Agent to handle high-load scenarios without crashing the underlying operating system. ### Systemd Configuration Settings These configuration options define the resource boundaries and recovery rules for the Frends Agent. The following table provides the default values for the Agent, introduced in version 6.3.1, and a brief explanation of how each setting contributes to overall stability.
OptionDefault ValueExplanation
MemoryHigh75%Soft limit where the kernel throttles the Agent and swaps out cold pages; slows performance but does not terminate the service. Can also be absolute value such as 2G.
MemoryMax90%Hard limit that causes an OOM-kill if reached, protecting the host machine from a total crash. Can also be absolute value such as 3G.
MemorySwapMax3GCaps the Agent's swap usage to prevent a memory leak from thrashing the host; sized against a default 4 GB swap file.
OOMPolicystopConfigures the service to stop cleanly on an Out-Of-Memory event so the auto-restart mechanism can trigger.
Restarton-failureDetermines the conditions under which the service manager automatically restarts the Agent.
RestartSec60The duration the system waits before attempting to restart the service after a failure, in seconds.
StartLimitBurst5The maximum number of restart attempts permitted within the defined interval to ride out temporary resource pressure.
StartLimitIntervalSec600The timeframe used to calculate the frequency of restart attempts to prevent infinite loops for broken Agents.
TimeoutStopSec300The hard limit on how long the service manager waits during shutdown before issuing a SIGKILL .
### Applying the configurations Configurations should be applied using drop-in override files rather than modifying the main service file. This ensures your settings persist through Frends updates. Run the following command to open the override editor: ``` sudo systemctl edit frends-agent ``` Place your custom settings under the `[Service]` section. For example, you can set absolute limits instead of percentages. ``` [Service] MemoryHigh=2G MemoryMax=3G ``` After saving, apply the changes and restart the service. ``` sudo systemctl daemon-reload sudo systemctl restart frendsagent ``` ## Shutdown and Stop Behavior To ensure the Agent flushes logs and checkpoints hydration state, align the `Shutdown.Timeout` in `appsettings.json` to be lower than the `systemd` `TimeoutStopSec`. While the default 7-day application timeout accommodates long-running Processes, it must not exceed the system stop limit, or the operating system will issue a `SIGKILL` before the flush completes, potentially losing execution state data. ## Memory and Swap Management `MemoryHigh` and `MemoryMax` define the Agent's resource boundaries. Because executions run in-process, reaching `MemoryMax` terminates the entire service. Stability is managed through two paths: the .NET Garbage Collector caps the managed heap at 75% of `MemoryMax` to trigger clean restarts via `OutOfMemoryException`, while `MemoryHigh` allows the kernel to reclaim native memory and buffers. This throttling requires active swap space because the .NET heap is anonymous memory. On swapless hosts, Agents often run straight to `MemoryMax` and are killed. A 4 GB swap file is the recommended baseline; on larger hosts, scale the swap file and `MemorySwapMax` proportionally to maintain a functional throttling zone without exhausting system resources. ## Scenario Based Tuning Smaller hosts with limited RAM should use absolute values like `MemoryMax=2G` instead of percentages to ensure the OS has enough reserved memory. For shared environments where multiple services run together, absolute limits prevent the Agent from competing for the entire system's resources. In high-performance, memory-tight or service-critical environments, the .NET Garbage Collector can be tuned by adding `Environment=DOTNET_GCConserveMemory=3` to the service configuration. This reduces the memory footprint at the cost of a slight increase in CPU overhead. ## Configuration Verification You can confirm that your settings are active by checking the service status and cgroup configuration. Running `stat -fc %T /sys/fs/cgroup` verifies you are using `cgroup2fs`, which is necessary for these memory controls. You can also confirm that the swap space is enabled through command `swapon --show`. The active limits and current memory usage of the Agent service can be viewed by executing the following command: ``` systemctl show frends-agent -p MemoryMax -p MemoryCurrent -p MemorySwapMax -p MemorySwapCurrent ``` ### Checking for OOM Events It is also useful to check system logs for Out-Of-Memory events to understand if the Agent has been previously terminated. The command `journalctl -u frends-agent -b | grep -iE 'oom|killed'` will display any recent instances where the system was forced to stop the service due to resource exhaustion. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.frends.com/guides/setup-and-installation/tuning-memory-usage-and-recovery-for-frends-agent-on-linux.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.