The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
---
title: "Windows Install"
description: "Install the Beacon endpoint on Windows with the MSI, and understand how the Windows service is managed"
---
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](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it:
<CodeGroup>
```powershell title="Interactive"
msiexec /i BeaconEndpointAgent-<version>-x64.msi
```
```powershell title="Silent, for fleet deployment"
msiexec /i BeaconEndpointAgent-<version>-x64.msi /qn /l*v install.log
```
</CodeGroup>
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.
A first install sets up [restricted log access](/security/restricted-log-access#on-windows): only the SYSTEM collector writes the log, and only SYSTEM, Administrators and the `beacon-log` local group can read it. An upgrade keeps the mode the endpoint already has. Installing interactively adds the account signed in at the console to `beacon-log`, so the dashboard, `beacon traces` and `beacon share` work for it after signing in again; a silent install (`/qn`) adds nobody and turns the [local dashboard](/cli/dashboard#turning-the-dashboard-off) off, unless `BEACON_DASHBOARD=enabled` is set. See [Package installs](/security/restricted-log-access#package-installs).
### Settings for fleet installs
The MSI cannot take environment variables from Intune or SCCM, so its install step also reads the install settings as string values under `HKLM\SOFTWARE\Policies\Beacon\Endpoint`, named exactly like the variables. Set them before installing, with an Intune or Group Policy registry setting, or:
```powershell title="Install settings as policy values (elevated)"
New-Item -Path 'HKLM:\SOFTWARE\Policies\Beacon\Endpoint' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Beacon\Endpoint' -Name BEACON_LOG_ACCESS -Value restricted
Set-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Beacon\Endpoint' -Name BEACON_LOG_READERS -Value ''
```
An empty `BEACON_LOG_READERS` value means nobody is added to `beacon-log` implicitly. A variable set in the install step's environment wins over the policy value. The values are read on every install and upgrade.
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):
```powershell title="Find the logs of Beacon's install and uninstall steps"
Get-ChildItem "$env:SystemRoot\Temp", "$env:SystemRoot\SystemTemp" -Filter 'beacon-package-*.log' -ErrorAction SilentlyContinue |
Sort-Object LastWriteTime
```
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.
<Warning>
**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:
```powershell
(Get-FileHash BeaconEndpointAgent-<version>-x64.msi -Algorithm SHA256).Hash
```
Authenticode signing is planned. Until then, the checksum is the only integrity check the package has.
</Warning>
<Note>
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.
</Note>
## Confirm it worked
```powershell title="Verify the install"
& "$env:ProgramFiles\Beacon\bin\beacon.exe" endpoint status --system
```
```
Beacon Endpoint Agent 1.0.6
Config: C:\ProgramData\Beacon\Endpoint\config.json
Runtime log: C:\ProgramData\Beacon\Endpoint\logs\runtime.jsonl
Collector: grpc=true http=true
Service: loaded=true running=true
Harness: Claude Code telemetry=enabled
Last event: present
```
`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:
```powershell title="Confirm you have a real service, not the fallback"
beacon endpoint status --system --json | Select-String '"kind"'
```
```
"service":{"label":"BeaconCollector","loaded":true,"running":true,"kind":"windows-service"}
```
`"kind":"windows-service"` is what you want. `"kind":"none"` means the supervised fallback. See [user-mode install](#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:
```
Beacon endpoint doctor: warn
harness_observed: warn target=claude_code (telemetry is configured but no matching event has
been observed yet) action="run Claude Code or beacon endpoint test-event"
Summary: 0 failure(s), 1 warning(s)
```
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:
```powershell title="Prove the collector is receiving and writing events"
beacon endpoint test-event --system
```
<Note>
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.
</Note>
## Using it
Run your agent the way you normally do:
```powershell
claude
```
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:
| Path | Carries |
|---|---|
| OpenTelemetry | Prompts, tool calls, token usage, and cost, through `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317` in your agent settings |
| Hooks | Session start and end, tool use, permission requests, subagent activity, and reasoning |
Both are loopback-only. Nothing leaves the machine.
From there:
```powershell title="Look at what was captured"
beacon endpoint dashboard # local web view of sessions, timelines, and event detail
beacon scan # run threat detection rules over the log
beacon token-usage # token and cost rollups
```
An unattended package install, such as one from a configuration manager or MDM, turns the dashboard off unless `BEACON_DASHBOARD=enabled` was set; see [Turning the dashboard off](/cli/dashboard#turning-the-dashboard-off).
See the [event schema](/telemetry-schema/event-schema) for the full field reference.
## What the install does
| Step | Result |
|---|---|
| Unpack | `beacon.exe`, `beacon-hooks.exe`, `beacon-otelcol.exe`, and `vector.exe` under `%ProgramFiles%\Beacon\bin` |
| System install | Config and collector config under `%ProgramData%\Beacon\Endpoint`, with `%ProgramData%\Beacon` owned by Administrators and locked down |
| Service | `BeaconCollector`, registered with the SCM, automatic start, restart on failure |
| Runtime log | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl` |
| Log permissions | `INTERACTIVE` may append to the runtime log files, and nothing more |
| Agent runtime | Claude Code and Codex CLI settings for the interactive user, pointed at `127.0.0.1:4317` |
`vector.exe` is [Vector](https://vector.dev) 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:
| Path | Owner | Access |
|---|---|---|
| `%ProgramData%\Beacon` and everything below it | Administrators | SYSTEM and Administrators: full control. Users: read and execute |
| `%ProgramData%\Beacon\Endpoint\logs` | Administrators | The same, plus `INTERACTIVE`: read and write data on files directly in the directory (inherit-only). No right to create, delete or rename entries, and no right to change a file's permissions or owner |
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](/log-forwarding/local-jsonl#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:
```powershell title="Reset the log directory ACL"
beacon endpoint doctor --system --fix
```
**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:
```powershell title="Configure your own agent runtime against an already-installed endpoint"
beacon endpoint user-config repair-installed --system
```
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:
```powershell title="Service management"
sc.exe query BeaconCollector
Restart-Service BeaconCollector
Get-Service BeaconCollector
```
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:
```powershell title="Repair the service"
beacon endpoint doctor --system --fix
```
## 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:
```powershell title="User-mode install"
beacon endpoint 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:
```powershell title="Upgrade in place"
msiexec /i BeaconEndpointAgent-<newer>-x64.msi /qn
```
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.
<Note>
`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.
</Note>
## Uninstall
Remove it from **Settings → Installed apps**, or from a command line:
```powershell title="Remove, keeping config and logs"
msiexec /x BeaconEndpointAgent-<version>-x64.msi /qn
```
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:
```powershell title="Remove everything, including configuration and logs"
$env:BEACON_PURGE = '1'
& "$env:ProgramFiles\Beacon\scripts\uninstall-endpoint.ps1"
msiexec /x BeaconEndpointAgent-<version>-x64.msi /qn
```
To remove a non-package install, use Beacon directly:
```powershell title="Full uninstall"
beacon endpoint uninstall --system
```
`--keep-logs` and `--keep-config` are available if you want to keep either.
## Known gaps
| Gap | Status |
|---|---|
| The installer is unsigned | SmartScreen warns. Verify the published `.sha256`. Authenticode signing is planned |
| `beacon endpoint update --apply` | Not supported on Windows. It refuses rather than pretending. Waiting on signing |
| `beacon ci exec` | Captures intermittently on Windows ([#320](https://github.com/asymptote-labs/agent-beacon/issues/320)). The installed-hook path on this page is unaffected |
| User-mode collectors | Do not restart and do not survive sign-out, because Windows has no per-user service manager |
| Windows ARM | No package, because there is no ARM collector build |
| WSL | A Claude Code running inside WSL writes to the Linux filesystem and needs the Linux build, not this one |
## Related
<Columns cols={2}>
<Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">
Inspect collector health, runtime log state, harnesses, and diagnostics.
</Card>
<Card title="Endpoint paths and ports" icon="folder-tree" href="/cli/endpoint-paths">
Where Beacon writes config, logs, and service definitions on each platform.
</Card>
<Card title="Endpoint install" icon="download" href="/cli/endpoint-install">
All install flags, harness selection, and hook installation.
</Card>
<Card title="Endpoint doctor" icon="stethoscope" href="/cli/endpoint-doctor">
Diagnose and repair an existing install.
</Card>
<Card title="Local dashboard" icon="chart-line" href="/cli/dashboard">
Browse captured sessions, timelines, and event detail locally.
</Card>
<Card title="Threat detection" icon="shield-halved" href="/cli/scan">
Run the open threat rules over your runtime log, offline.
</Card>
</Columns>