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 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

Two of those rows deserve explanation. The log permission grant. A system-mode collector runs as LocalSystem and creates the log, while 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. Nothing reports it either, 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 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.