Getting started¶

FreeDR runs as one Windows service (FreeDR, display name FreeDR Endpoint Agent) on the computer it protects. You use it through a local web console at http://127.0.0.1:29173/ and a tray icon. Nothing is sent off the machine unless you turn on optional AI or threat-intel lookups.

Pre-release

FreeDR is pre-release software. Native Windows qualification is still in progress, and evidence data from older, incompatible pre-release builds is not migrated (see Upgrading).

Requirements¶

Requirement	Details
Operating system	x64 Windows 10 or Windows 11. Home, Pro, Enterprise and Education all work. On Home, features that Windows Home lacks (for example AppLocker) show as not applicable.
Administrator rights	Setup asks for elevation (UAC). Installing the service, creating the protected data folder and installing Sysmon need it.
Port 29173	The console listens on `127.0.0.1:29173`. If another program already uses that port, setup stops and tells you which process holds it.
Internet (first install only, if Sysmon is missing)	If Sysmon is not installed, setup downloads it from Microsoft (`download.sysinternals.com`). For an offline install, install Sysmon yourself first.
Password	You choose a FreeDR password of at least 12 characters (at most 1024 bytes).

Sysmon¶

FreeDR reads Sysmon events from the Microsoft-Windows-Sysmon/Operational event log. It does not ship Sysmon (Microsoft's license does not allow that).

Sysmon already installed (Sysmon64 or Sysmon service exists): FreeDR does not touch it or its configuration.
Sysmon not installed: setup downloads Sysmon.zip from Microsoft, checks it against a pinned SHA-256 hash, and installs Sysmon64.exe with FreeDR's configuration (sysmon-freedr.xml). The download and install have a 5-minute time limit. If the download fails or its hash does not match the pinned release, the FreeDR install fails. In that case, install Sysmon yourself and run setup again.
FreeDR never reconfigures or removes Sysmon. You can also install it later from Settings › Sources (see Sources).

Install with the setup wizard¶

FreeDR-Setup.exe is a single file. It contains the agent, the tray app and the DuckDB runtime. Run it and approve the UAC prompt.

Wizard pages¶

Page	What you do
Welcome	Shows what will be installed: the FreeDR service, its tray icon, and Sysmon if it is missing. You can optionally Import configuration file… (a JSON file, format below). Its values fill in the next pages for you to review.
Administrator password	Choose the console password and confirm it (at least 12 characters). If data from an earlier install is found, enter that installation's password to keep the data instead.
AI investigator (optional)	Enable AI investigation, Provider, Thinking level, Model ID, API key, Let AI contain threats it finds (off by default) and Enable public web research (off by default). Changing the provider fills in that provider's default model and thinking level.
Threat-intel keys (optional)	Keys for abuse.ch (MalwareBazaar, ThreatFox, URLhaus), AbuseIPDB, VirusTotal, AlienVault OTX and GreyNoise Community. Leave a field empty to skip it. CIRCL needs no key.
Installing	Progress log.
Done	Result. Open FreeDR now (checked by default) opens the console in your browser as your normal, non-elevated user.

AI provider choices and defaults:

Provider	Config value	Default model	Thinking levels (default bold)
CheaperInference	`cheaper_inference`	`deepseek-v4.1-flash`	none, low, medium, high, xhigh, max
OpenAI	`open_ai`	`gpt-6.1-sol`	none, low, medium, high, xhigh, max
Anthropic	`anthropic`	`claude-sonnet-5-5`	disabled, between_tools, low, medium, high, xhigh, max
DeepSeek	`deep_seek`	`deepseek-flash`	disabled, low, high, max

Anthropic's disabled and between_tools work only on some models. See AI features for what the AI investigator does.

What setup does¶

Unpacks its files into a new temporary folder, C:\ProgramData\FreeDR-Setup-<pid>-<nonce>. Only SYSTEM and Administrators can write to it. Setup deletes it afterwards.
Runs the agent's own installer. This step creates C:\ProgramData\FreeDR with protected permissions, stores the password, installs Sysmon if needed, copies the program files and registers and starts the FreeDR service (automatic start).
Waits up to 3 minutes for the FreeDR service process itself to listen on port 29173. Setup checks that the listening process is the service. If any other process holds the port, setup refuses to send it anything.
Signs in with your password and saves your AI settings, threat-intel keys and rule exclusions through the same local API that the Settings page uses. The same checks, encrypted key storage and audit records apply. A threat-intel key also turns on every provider that uses it.

Secrets go to the agent only through a pipe or the loopback API. Setup never writes them to disk or logs them.

Existing installation or data¶

What setup finds	What happens
Nothing	Fresh install. You set a new password.
`C:\ProgramData\FreeDR\password.json` exists, but no `FreeDR` service	Existing data is kept. The password page asks for that data's password. A wrong password fails the install.
The `FreeDR` service is installed	Setup switches to Uninstall FreeDR. It does not install over an existing installation. See Uninstalling.

If setup installs FreeDR but cannot apply the AI, key or exclusion settings, it says so. FreeDR still runs; enter those settings in Settings.

Command-line (unattended) install¶

FreeDR-Setup.exe /config <file.json>    install and apply the configuration file
FreeDR-Setup.exe /unattended            install with no extra configuration

--config and --unattended also work. There is no wizard in this mode:

Setup reads the password from the first line of standard input. It is never accepted as an argument.
Progress and errors go to standard error.
The whole file is checked before anything is installed. A bad key or unknown field stops setup with exit code 2.

Exit code	Meaning
0	Installed and configured
1	Not installed
2	Invalid input (bad file, password shorter than 12 characters, bad arguments)
3	Installed, but the configuration was not (fully) applied. Enter it in Settings.

Setup is a Windows (GUI) program, so run it from an elevated PowerShell and redirect its input and output. For example:

$p = Start-Process .\FreeDR-Setup.exe -ArgumentList '/config','freedr-setup.json' `
     -RedirectStandardInput password.txt -RedirectStandardError setup.log `
     -Wait -PassThru
$p.ExitCode
Remove-Item password.txt   # don't leave the password on disk

Configuration file¶

The file is JSON. Unknown fields are rejected. Every section is optional except schema_version.

{
  "schema_version": 1,
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-5-5",
    "api_key": "…",
    "thinking": "medium",
    "enabled": true,
    "web_enabled": false,
    "response_enabled": false,
    "daily_token_limit": 20000000
  },
  "enrichment": {
    "abuse_ch": "…",
    "abuse_ipdb": "…",
    "virus_total": "…",
    "alien_vault_otx": "…",
    "grey_noise": "…"
  },
  "rule_exclusions": [
    { "rule_id": "…", "predicate": "…", "reason": "…" }
  ]
}

Field	Required	Default	Rules
`schema_version`	yes	—	Must be `1`.
`ai.provider`	yes, if `ai` is present	—	`cheaper_inference`, `open_ai`, `anthropic` or `deep_seek`
`ai.api_key`	yes, if `ai` is present	—	1–4096 printable ASCII characters, no spaces
`ai.model`	no	the provider's default model	1–128 characters: letters, digits, `. _ : / -`
`ai.thinking`	no	the provider's default (see table above)	One of the provider's own thinking levels
`ai.enabled`	no	`true`	Turns AI investigation on
`ai.response_enabled`	no	`false`	Lets AI run containment steps on items it cites
`ai.web_enabled`	no	`false`	Allows public web research
`ai.daily_token_limit`	no	`20000000`	400,000 to 20,000,000
`enrichment.<slot>`	no	—	Slots: `abuse_ch`, `abuse_ipdb`, `virus_total`, `alien_vault_otx`, `grey_noise`. Same key rules as `api_key`. A key turns on the providers that use it.
`rule_exclusions[].rule_id`	yes, per entry	—	1–128 characters: letters, digits, `. _ -`
`rule_exclusions[].predicate`	yes, per entry	—	Not empty, at most 8192 bytes. Uses the rule exclusion syntax (Rules).
`rule_exclusions[].reason`	yes, per entry	—	Not empty, at most 1024 bytes
`rule_exclusions`	—	`[]`	At most 200 entries

The file holds secrets, so store and delete it carefully. Setup only reads it.

Install from the program folder (alternative)¶

You can also run freedr-agent.exe directly from a folder that contains freedr-agent.exe, freedr-tray.exe and duckdb.dll. It asks for elevation, then asks for the password in a console window (new password plus confirmation, or the existing data's password). It does the same install as setup, without the AI and key pages. From an already elevated prompt, freedr-agent.exe --password-stdin reads the password lines from standard input instead.

Open http://127.0.0.1:29173/. Setup's Open FreeDR now checkbox or the tray icon can open it for you.
Sign in with your FreeDR password.

Behaviour	Value
Address	Loopback only (`127.0.0.1`). The console cannot be bound to a network address.
Session lifetime	12 hours. Sign out ends the current session.
Sessions ended by	Signing out, a password change (ends all sessions) or a service restart
Failed-login throttle	5 attempts per minute
Forgotten password	There is no reset in the console, and running setup again does not reset it. Recovery needs an administrator to reset the installation.

Collection and detection keep running when you sign out or close the browser.

Tray icon¶

The service starts freedr-tray.exe in the session of the user signed in at the console, using that user's own account. The icon shows the current state:

Icon tooltip	Meaning
FreeDR · No unresolved alerts	All good
FreeDR · Unresolved alerts	There are alerts to review
FreeDR · Protection degraded	A component is degraded. Check Health.
FreeDR · Host isolated	The host is network-isolated
FreeDR · Host may be isolated – check console	The isolation state is uncertain

Click the icon or use the menu's Open console to open the console. Exit closes the tray until you next sign in. If the tray crashes, the service restarts it.

The tray also shows Windows alert notifications if you turn them on. They are off by default; see Configuration.

Where files live¶

Everything is under C:\ProgramData\FreeDR. Only SYSTEM and Administrators can access this folder.

Path	Contents
`freedr-agent.exe`, `freedr-tray.exe`, `duckdb.dll`	Program files
`password.json`	Console password verifier (not the password itself)
`ai-credential.dpapi`	The AI harness's own machine credential, generated at install and DPAPI-encrypted. This is not your provider API key.
`freedr.toml`	Optional startup configuration. Not created by default; see Agent configuration file.
`config\evidence-lifecycle.json`	Retention policy, edited from Settings › Storage
`config\telemetry-filters.toml`	Optional telemetry filter policy. Not created by default.
`data\evidence.duckdb`	Hot evidence database
`data\control.sqlite3`	Alerts, cases, rule state, settings, encrypted provider keys, audit records
`data\cold\`	Cold evidence as compressed Parquet files
`response-vault\`	Encrypted copies of quarantined files
`run\agent.log`	Service warnings and errors (size-capped)
`run\last-shutdown-spans.json`	Diagnostics from the last requested stop
`sysmon-freedr.xml`, `install-sysmon.ps1`	Written if FreeDR installed Sysmon

Browser display preferences (Appearance) are kept in the browser, not here.

Upgrading¶

Setup does not upgrade in place over a running install; with the FreeDR service present it offers only to uninstall. To move to a new build and keep your data:

Uninstall with Keep FreeDR data ticked (see Uninstalling).
Run the new FreeDR-Setup.exe. It detects the existing data and asks for that data's password.
The new program files replace the old ones. Alerts, cases, rules, settings and evidence are kept. The control database updates its schema automatically on first start.

FreeDR is pre-release, so data from much older, incompatible builds can be refused at startup. For example, the agent will not start if it finds the legacy data\evidence.sqlite3 evidence file. In that case, start with a fresh data folder.

Uninstalling¶

Run FreeDR-Setup.exe (any build). When FreeDR is installed, the wizard opens as Uninstall FreeDR:

Choose Next, enter the FreeDR password and, to keep the data for a later installation, tick Keep FreeDR data (evidence, cases, settings and password).
Choose Uninstall and confirm.

Setup then:

stops and deletes the FreeDR service, which also closes the tray icon;
removes every Windows Filtering Platform filter FreeDR added, so any traffic block or host isolation is lifted;
deletes C:\ProgramData\FreeDR, or, with Keep FreeDR data, only the program files (freedr-agent.exe, duckdb.dll, freedr-tray.exe).

A wrong password stops the uninstall before anything is changed. Files that FreeDR quarantined stay quarantined in place. There is no Apps & features entry.

Unattended, from an elevated prompt (password on the first line of standard input):

FreeDR-Setup.exe /uninstall [/keep-data] < password.txt

Exit codes: 0 uninstalled, 1 not installed or failed, 2 invalid input.

Sysmon stays installed. Remove it yourself if you want to (Sysmon64.exe -u).

Windows audit-policy or event-channel changes you made from Settings › Sources stay in place. Use Restore on that page before uninstalling to undo them.

freedrctl (command line)¶

freedrctl.exe is a small command-line client. It is built from the source tree and is not included in FreeDR-Setup.exe.

Command	What it does
`freedrctl status`	Agent status (`/status`)
`freedrctl version`	Agent version
`freedrctl alerts`	Alert list (JSON)
`freedrctl rules`	Detection rules (JSON)
`freedrctl detection-health`	Detection health (JSON)
`freedrctl service start \\| stop \\| status \\| uninstall`	Controls the Windows service. Needs administrator rights and the FreeDR password.

Global options:

--port <n> uses a different local API port (default 29173).
--password-stdin reads the password from standard input instead of a hidden prompt. Passwords are never accepted as arguments or environment variables.

Each command signs in, makes its request and signs out again. freedrctl service install is not supported; use setup.