Agent configuration file (freedr.toml)

The service reads C:\ProgramData\FreeDR\freedr.toml once, at startup. The file is optional and is not created by install. Without it, all defaults apply. Most users never need it.

• Changes take effect after a service restart (sc.exe stop FreeDR then sc.exe start FreeDR, from an elevated prompt).
• Unknown keys, values out of range, or a file larger than 64 KiB stop the service from starting. Check run\agent.log if it does not start.
• The folder is protected, so only Administrators can create or edit the file.

Full file with defaults

version = 1
hot_retention = 2700              # seconds
shutdown_timeout_seconds = 30

[api]
bind = "127.0.0.1"
port = 29173

[etw]
process_worker_count = 2
registry_worker_count = 8
file_worker_count = 2

[artifact]
control_capacity = 16384

Fields

Field	Default	Allowed	Meaning
version	1	1 only	File format version
hot_retention	2700 (45 min)	at least 2700 seconds	How long evidence stays in the hot database before it moves to cold Parquet files. Also sets how often cold export runs. Detections read hot data only, so 45 minutes is the minimum.
shutdown_timeout_seconds	30	30 only	Service shutdown deadline. It is fixed; any other value is rejected.
api.bind	127.0.0.1	127.0.0.1 only	The console and API listen on loopback only. Any other address is rejected.
api.port	29173	1–65535	Console/API port. Setup always expects 29173, so change the port only after installing. The tray uses the configured port. For freedrctl, pass --port.
etw.process_worker_count	2	2, 4 or 8	Decode threads for the process ETW stream
etw.registry_worker_count	8	2, 4 or 8	Decode threads for the registry ETW stream
etw.file_worker_count	2	2, 4 or 8	Decode threads for the file ETW stream
artifact.control_capacity	16384	1–16384	Maximum queued explicit artifact (file) collection requests

The ETW worker counts are tuning controls; the defaults are what has been tested. The console's evidence retention period is a separate setting, changed in Settings › Storage (see Configuration).

Environment-variable overrides

The service also reads these variables from its process environment. They take priority over freedr.toml:

Variable	Overrides
FREEDR_API_PORT	api.port
FREEDR_HOT_RETENTION	hot_retention
FREEDR_SHUTDOWN_TIMEOUT_SECONDS	shutdown_timeout_seconds
FREEDR_ETW_PROCESS_WORKER_COUNT	etw.process_worker_count
FREEDR_ETW_REGISTRY_WORKER_COUNT	etw.registry_worker_count
FREEDR_ETW_FILE_WORKER_COUNT	etw.file_worker_count
FREEDR_ARTIFACT_CONTROL_CAPACITY	artifact.control_capacity

Warning

Any other variable whose name starts with FREEDR_ in the service's environment (for example a system-wide variable) is treated as an error, and the service will not start.

Telemetry filter policy (advanced)

C:\ProgramData\FreeDR\config\telemetry-filters.toml is optional. When the file is absent, FreeDR uses its built-in policy. That policy drops:

• FreeDR's own internal storage file and registry I/O;
• successful file open/read probes by signed Microsoft Defender (MsMpEng.exe, service WinDefend);
• registry open/query/enumerate noise from a few signed Microsoft components: Network Setup Service, Capability Access Manager, Delivery Optimization, Widgets, the Widgets Platform Runtime, and one measured COM surrogate.

If you create the file, it replaces the built-in policy completely; it is not merged with it.

The format is version = 1, revision (1 or higher) and up to 32 [[profiles]]. Each profile has:

• id: lowercase letters, digits and hyphens;
• enabled, revision and rationale;
• an [profiles.identity] table: canonical_image (at most one *), require_trusted_signature, and optionally signer_publisher_prefix, service_name, package_family_prefix and com_app_id;
• sources: file and/or registry;
• operations: internal, open, read, query or enumerate.

Profiles that target WMI are refused. If the file fails validation, the service still starts, but logs a warning and turns filtering off entirely. Only filter what you have measured: filtered events are never stored.