> ## Documentation Index > Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt > Use this file to discover all available pages before exploring further. # Windows Install > 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--x64.msi` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and install it: ```powershell title="Interactive" theme={null} msiexec /i BeaconEndpointAgent--x64.msi ``` ```powershell title="Silent, for fleet deployment" theme={null} msiexec /i BeaconEndpointAgent--x64.msi /qn /l*v install.log ``` 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: ```powershell theme={null} (Get-FileHash BeaconEndpointAgent--x64.msi -Algorithm SHA256).Hash ``` 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 ```powershell title="Verify the install" theme={null} & "$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" theme={null} 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" theme={null} beacon endpoint test-event --system ``` 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: ```powershell theme={null} 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" theme={null} 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 ``` 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`, and `beacon-otelcol.exe` under `%ProgramFiles%\Beacon\bin` | | System install | Config and collector config under `%ProgramData%\Beacon\Endpoint` | | Service | `BeaconCollector`, registered with the SCM, automatic start, restart on failure | | Runtime log | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl` | | Log permissions | Write access granted to `INTERACTIVE`, so hooks running as you can append | | Agent runtime | Claude Code and Codex CLI settings for the interactive user, pointed at `127.0.0.1:4317` | 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: ```powershell title="Configure your own agent runtime against an already-installed endpoint" theme={null} 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" theme={null} 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" theme={null} 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" theme={null} 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" theme={null} msiexec /i BeaconEndpointAgent--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. `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: ```powershell title="Remove, keeping config and logs" theme={null} msiexec /x BeaconEndpointAgent--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" theme={null} $env:BEACON_PURGE = '1' & "$env:ProgramFiles\Beacon\scripts\uninstall-endpoint.ps1" msiexec /x BeaconEndpointAgent--x64.msi /qn ``` To remove a non-package install, use Beacon directly: ```powershell title="Full uninstall" theme={null} 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 Inspect collector health, runtime log state, harnesses, and diagnostics. Where Beacon writes config, logs, and service definitions on each platform. All install flags, harness selection, and hook installation. Diagnose and repair an existing install. Browse captured sessions, timelines, and event detail locally. Run the open threat rules over your runtime log, offline.