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 installer is not code-signed yet. Windows SmartScreen will warn that the publisher is unknown, and you will need to choose “More info” then “Run anyway”. Verify what you downloaded against the published .sha256 before you do:
Authenticode signing is planned; until then the checksum is the integrity check the package has.
x64 only. There is no Windows ARM package, because there is no Windows ARM build of the collector the package would need to contain — an installer that put the CLI on disk without it 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 reports running=true too. The JSON output names it:
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, checking the whole chain — service, collector, config, log permissions, and each harness’s settings — and printing the command to fix anything it finds. On a fresh install it reports one warning, and it is not a problem:
That says “configured correctly, but you have not used it 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

Nothing to remember. Run your agent the way you normally do:
Prompts, the commands the agent runs, files it reads and writes, token counts and cost, approvals and denials all land in C:\ProgramData\Beacon\Endpoint\logs\runtime.jsonl — one JSON object per line. Two independent paths feed it, which is why 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

Two of those rows deserve explanation. The log permission grant. A system-mode collector runs as LocalSystem and creates the log; hooks run as you and append to it. %ProgramData% subdirectories inherit an ACL where only administrators and SYSTEM may write, so without an explicit 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 install grants INTERACTIVE write access on the log directory, and doctor checks the grant is still there. 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 is exporting 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 — a collector that cannot start at all should leave a visible stopped service rather than thrash. 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

If you do not want a system service — a machine where you are not an administrator, or where you only want your own sessions captured — install in user mode:
User-mode install
This writes everything under %USERPROFILE%\.beacon\endpoint. One limitation has no macOS or Linux equivalent and is worth stating plainly: 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. Two consequences, both of which beacon endpoint status states in-band rather than leaving you to discover:
  • 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 equivalent, which is why the system-mode install is the recommended path here even for a single-user machine.

​
Which shell your agent uses

Worth knowing if you are debugging a hook that is not firing: Claude Code on Windows executes 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. This was measured rather than assumed — a probe installed several candidate command forms and reported which ones ran. If you write your own hook commands alongside Beacon’s, they are parsed by bash 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 rather than tidy: Windows cannot replace a file that a running process holds open, so an upgrade that left the collector running would either 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 recognises, rather than pretending to update. Self-update is waiting on code signing — downloading and running an unsigned installer automatically would be 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

Stated here rather than left to be discovered:

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.