Skip to main content
Beacon runs a local collector on your machine, points your agent runtimes at it, and writes normalized events to a JSONL log you own. On Windows the collector runs as a Windows service, managed by the Service Control Manager. Installing the package is the whole setup. It unpacks the binaries, performs the system-mode install, registers and starts the BeaconCollector service, and configures the runtime of the interactive user. There is no second command to run.

​
Install

Download BeaconEndpointAgent-<version>-x64.msi from the latest release and install it:
The install needs administrator rights, because it writes under %ProgramData% and registers a service. Elevation is requested for you when you double-click the package. A silent install must already be running elevated, which is the normal case for Intune, SCCM, or a management agent. The /l*v log records what Windows Installer did, but not what Beacon’s own install and uninstall steps printed. Those go to a separate log for each run, in the temporary directory of the account that ran the package (C:\Windows\Temp when a management agent installs as SYSTEM):
Find the logs of Beacon's install and uninstall steps
Each step has a time limit: 10 minutes for the install, 5 for configuring the signed-in user’s agent, and 3 for the uninstall. A step that runs past its limit is stopped, so the package finishes instead of hanging your deployment tool, and the log records the step and where it was stuck. An install stopped this way fails, so your deployment tool reports it. An uninstall stopped this way stops and removes the BeaconCollector service itself, so the removal or upgrade can finish.
The installer is not code-signed yet. Windows SmartScreen warns that the publisher is unknown, and you need to choose “More info” then “Run anyway”. Verify what you downloaded against the published .sha256 first:
Authenticode signing is planned. Until then, the checksum is the only integrity check the package has.
x64 only. There is no Windows ARM package, because there is no Windows ARM build of the collector to put in it. An installer that shipped the CLI without a collector would report “no collector found” on a machine where you had just installed Beacon.

​
Confirm it worked

Verify the install
running=true alone does not tell you which backend you got. Beacon falls back to a supervised background collector when it cannot register a service, and the fallback also reports running=true. The JSON output names the backend:
Confirm you have a real service, not the fallback
"kind":"windows-service" is what you want. "kind":"none" means the supervised fallback. See user-mode install for what that costs you. beacon endpoint doctor --system goes further. It checks the whole chain (service, collector, config, log permissions, and each harness’s settings) and prints the command to fix anything it finds. On a fresh install it reports one warning, which is not a problem:
That means “configured correctly, but not used yet”. It clears the first time you run your agent. What matters is 0 failure(s). To confirm the pipeline before running a real session, write a synthetic event from an elevated prompt:
Prove the collector is receiving and writing events
Pass --system here. Without it the command targets the user-mode log under your profile, which is not the log a system install writes to, so it would report success against the wrong file.

​
Using it

Run your agent the way you normally do:
Prompts, the commands the agent runs, files it reads and writes, token counts and cost, and approvals and denials all land in C:\ProgramData\Beacon\Endpoint\logs\runtime.jsonl, one JSON object per line. Two independent paths feed it, so a gap in one still leaves you with data: Both are loopback-only. Nothing leaves the machine. From there:
Look at what was captured
See the event schema for the full field reference.

​
What the install does

vector.exe is Vector 0.56.0, the log forwarder the macOS and Linux packages also carry. The package only installs it: nothing runs it until you set up a forwarder. If you run AppLocker or Windows Defender Application Control, allow the four programs in %ProgramFiles%\Beacon\bin. None of them is code-signed yet (see below), so a publisher rule cannot match them; use a path or file hash rule. Two of those rows deserve explanation. The directory and log permissions. A system-mode collector runs as LocalSystem and writes the log, while hooks run as you and append to it. %ProgramData% subdirectories inherit an ACL where ordinary users cannot write existing files, so without a grant every hook write fails with access denied, and nothing reports it, because status and doctor describe the collector rather than the hooks exporting to it. The grant has to stop there: a user who can add, delete or rename entries in a directory a SYSTEM process writes to can swap the log for a link and send the collector’s writes anywhere. So the install sets these ACLs, by well-known SID, with inheritance from %ProgramData% turned off: Because users cannot create files in the log directory, the install creates runtime.jsonl and runtime.jsonl.lock itself; files the collector creates later, such as the log it starts after a rotation, inherit the same append grant. Rotation is done by the collector and by beacon commands run as an administrator. A hook that finds the log over its size limit appends anyway and leaves the rename to them. A program that reads the log without allowing deletes, such as a PowerShell Get-Content loop, holds rotation up until it closes the file. The log grows past its size limit in the meantime and no events are lost. See Reading the log on Windows. %ProgramData%\Beacon is reset even when it already exists. %ProgramData% lets any user create a subdirectory, so one found there before the package was installed may belong to someone else: the install takes ownership, replaces its ACL, removes any junction, symbolic link or hard link inside it (Beacon creates none), and resets anything below it that grants an ordinary user write, delete or ownership rights. Anything already locked down further than this is left as it is. A few things below %ProgramData%\Beacon are kept from ordinary users entirely, with access for SYSTEM and Administrators only: config.json and otelcol.yaml when they hold a Splunk or Falcon HEC token, the OTLP forward’s headers, and Endpoint\state\backfill-snapshots, where the session backfill copies the signed-in user’s SQLite session stores to read them and deletes each copy once read. doctor --system checks both halves: that interactive users can append, and that nothing grants them more. An endpoint installed by an older version carries a broader grant (Modify for INTERACTIVE on the log directory) and is reported as acl_too_broad. Upgrading the package fixes it, as does running this from an elevated shell:
Reset the log directory ACL
The agent runtime row. A system-mode endpoint is installed by an administrator or by a management agent running as LocalSystem, neither of which is necessarily the person at the keyboard, and the collector is useless if nothing exports to it. Beacon works out who is signed in at the console and configures their runtime. If it cannot identify anyone, it says so instead of failing, and you can configure yourself later:
Configure your own agent runtime against an already-installed endpoint
Other users on the same machine run the same command for themselves. They all export to the same collector and the same log.

​
Managing the service

BeaconCollector is an ordinary Windows service, so the usual tools work:
Service management
The install sets automatic start with a delayed start, so the collector comes back after a reboot without anyone signing in and does not compete with the rest of boot. It also sets recovery actions: three restarts at 5, 15, and 60 seconds, with the failure count resetting after a day of health. Three escalating restarts rather than unlimited immediate ones means a collector that cannot start at all leaves a visible stopped service rather than thrashing. The SCM captures no stdout, so there is no journal equivalent. The collector’s own log is the place to look, and doctor reads it for you. If the service is missing or broken, repair it without reinstalling the package:
Repair the service

​
User-mode install

Install in user mode if you do not want a system service, either because you are not an administrator on the machine or because you only want your own sessions captured:
User-mode install
This writes everything under %USERPROFILE%\.beacon\endpoint. One limitation has no macOS or Linux equivalent: Windows has no per-user service manager. There is no counterpart to systemctl --user or launchd’s per-user domain, so a user-mode install runs a supervised background collector tracked by a pidfile. That has two consequences, both of which beacon endpoint status reports:
  • Nothing restarts it. If the collector exits, it stays down until you start it again.
  • It does not survive sign-out. Windows ends the session’s processes at logoff.
On Linux the equivalent gap is fixable with loginctl enable-linger. Windows has no counterpart, which is why system-mode install is the recommended path here even on a single-user machine.

​
Which shell your agent uses

This matters when you are debugging a hook that is not firing. Claude Code on Windows runs hook commands through Git Bash, not cmd.exe or PowerShell. Beacon’s installed hook commands are written for that, and Git Bash ships with Git for Windows, which Claude Code already requires. If you write your own hook commands alongside Beacon’s, bash parses those too.

​
Updates

Download the newer MSI and install it over the top:
Upgrade in place
The upgrade stops the endpoint, replaces the binaries, and brings it back. That ordering is required: Windows cannot replace a file a running process holds open, so an upgrade that left the collector running would fail, defer the replacement to your next reboot, or silently keep the old binary. Your configuration and collected log survive the upgrade.
beacon endpoint update --apply does not work on Windows yet. It reports that automatic apply is only supported for a package install it recognizes, rather than pretending to update. Self-update is waiting on code signing, because downloading and running an unsigned installer automatically is a worse trade than doing it by hand.

​
Uninstall

Remove it from Settings → Installed apps, or from a command line:
Remove, keeping config and logs
Removal stops and deletes the service and takes the binaries away, but leaves %ProgramData%\Beacon\Endpoint alone. Collected telemetry is not something a package removal should destroy, and an uninstall is often the first half of a reinstall. To remove that too:
Remove everything, including configuration and logs
To remove a non-package install, use Beacon directly:
Full uninstall
--keep-logs and --keep-config are available if you want to keep either.

​
Known gaps

Endpoint status

Inspect collector health, runtime log state, harnesses, and diagnostics.

Endpoint paths and ports

Where Beacon writes config, logs, and service definitions on each platform.

Endpoint install

All install flags, harness selection, and hook installation.

Endpoint doctor

Diagnose and repair an existing install.

Local dashboard

Browse captured sessions, timelines, and event detail locally.

Threat detection

Run the open threat rules over your runtime log, offline.