Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

docs(windows): document the Windows install and how to verify it

shukieshah073cc89c6408
diff --git a/README.md b/README.md
index 87ceda41..980598e3 100644
--- a/README.md
+++ b/README.md
@@ -162,14 +162,22 @@ Agent Beacon is designed for Security and IT teams to deploy and validate
through standard MDM workflows.
Version tags publish a signed, notarized, and stapled Apple Silicon endpoint
-`.pkg` to GitHub Releases for MDM/manual download, along with `.deb` and `.rpm`
-packages for Linux on amd64 and arm64. Homebrew and release archives remain
-available for CLI installs across supported macOS/Linux architectures.
-
-Installing a Linux package performs the system-mode install itself: it registers
-and starts a systemd unit, writes configuration to `/etc/beacon/endpoint`, and
-points the installing user's agent runtimes at the local collector. See the
-[Linux install guide](https://docs.asymptotelabs.ai/platforms/linux).
+`.pkg` to GitHub Releases for MDM/manual download, `.deb` and `.rpm` packages for
+Linux on amd64 and arm64, and an x64 `.msi` for Windows. Homebrew and release
+archives remain available for CLI installs across supported macOS, Linux, and
+Windows architectures.
+
+Installing a native package performs the system-mode install itself: it registers
+and starts the service, writes configuration to the platform's machine-wide
+location, and points the interactive user's agent runtimes at the local
+collector. See the [Linux install guide](https://docs.asymptotelabs.ai/platforms/linux)
+or the [Windows install guide](https://docs.asymptotelabs.ai/platforms/windows).
+
+| Platform | Package | Service manager | Notes |
+| --- | --- | --- | --- |
+| macOS | Signed, notarized `.pkg` (Apple Silicon) | launchd | Homebrew for single machines |
+| Linux | `.deb` / `.rpm` (amd64, arm64) | systemd | Supervised fallback without systemd |
+| Windows | `.msi` (x64) | Service Control Manager | Unsigned for now; verify the published `.sha256` |
| MDM platform | Support path |
| --- | --- |
diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdx
index 5de56949..985a8125 100644
--- a/docs/cli/endpoint-paths.mdx
+++ b/docs/cli/endpoint-paths.mdx
@@ -7,20 +7,25 @@ description: "Review Beacon user-mode and system-mode paths, ports, and hook loc
Beacon manages different paths depending on whether you install in user mode or system mode. The active runtime log stays at `runtime.jsonl` and rotates at 10 MiB, retaining five numbered local archives by default.
-| Item | User mode | System mode (macOS) | System mode (Linux) |
-|------|-----------|---------------------|---------------------|
-| Config | `~/.beacon/endpoint/config.json` | `/Library/Application Support/Beacon/Endpoint/config.json` | `/etc/beacon/endpoint/config.json` |
-| Base directory | `~/.beacon/endpoint` | `/Library/Application Support/Beacon/Endpoint` | `/etc/beacon/endpoint` |
-| Runtime log | `~/.beacon/endpoint/logs/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` |
-| Rotated runtime archives | `~/.beacon/endpoint/logs/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` |
-| Threat rule store | `~/.beacon/endpoint/rules` | `/Library/Application Support/Beacon/Endpoint/rules` | `/etc/beacon/endpoint/rules` |
-| Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` | `/etc/beacon/endpoint/otelcol.yaml` |
-| OTLP gRPC | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` |
-| OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` |
+| Item | User mode | System mode (macOS) | System mode (Linux) | System mode (Windows) |
+|------|-----------|---------------------|---------------------|-----------------------|
+| Config | `~/.beacon/endpoint/config.json` | `/Library/Application Support/Beacon/Endpoint/config.json` | `/etc/beacon/endpoint/config.json` | `%ProgramData%\Beacon\Endpoint\config.json` |
+| Base directory | `~/.beacon/endpoint` | `/Library/Application Support/Beacon/Endpoint` | `/etc/beacon/endpoint` | `%ProgramData%\Beacon\Endpoint` |
+| Runtime log | `~/.beacon/endpoint/logs/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl` |
+| Rotated runtime archives | `~/.beacon/endpoint/logs/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `/var/log/beacon-agent/runtime.jsonl.1` through `.5` | `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl.1` through `.5` |
+| Threat rule store | `~/.beacon/endpoint/rules` | `/Library/Application Support/Beacon/Endpoint/rules` | `/etc/beacon/endpoint/rules` | `%ProgramData%\Beacon\Endpoint\rules` |
+| Collector config | `~/.beacon/endpoint/otelcol.yaml` | `/Library/Application Support/Beacon/Endpoint/otelcol.yaml` | `/etc/beacon/endpoint/otelcol.yaml` | `%ProgramData%\Beacon\Endpoint\otelcol.yaml` |
+| Installed binaries | — | `/opt/beacon/bin` | `/opt/beacon/bin` | `%ProgramFiles%\Beacon\bin` |
+| OTLP gRPC | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` | `127.0.0.1:4317` |
+| OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` |
+
+On Windows the system log directory sits under the base directory rather than in a separate location,
+because there is no `/var/log` equivalent. `%ProgramData%` and `%ProgramFiles%` are read from the
+environment rather than hardcoded, so a relocated or localized install is found rather than missed.
## Service Definitions
-The collector runs under whichever service manager the host provides. Beacon picks it by looking at
+The collector runs under whichever service manager the host provides. On Linux, Beacon picks it by looking at
what is actually running as PID 1, not at which tools are installed, so a container with
`systemctl` on `PATH` but no systemd still gets the supervised fallback.
@@ -28,8 +33,14 @@ what is actually running as PID 1, not at which tools are installed, so a contai
|---|---|---|---|
| macOS | launchd | `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` | `~/Library/LaunchAgents/com.beacon.endpoint.collector.user.plist` |
| Linux | systemd | `/etc/systemd/system/beacon-collector.service` | `~/.config/systemd/user/beacon-collector.service` |
+| Windows | Service Control Manager | `BeaconCollector` service, defined at `HKLM\SYSTEM\CurrentControlSet\Services\BeaconCollector` | supervised — Windows has no per-user service manager |
| Containers, no init | supervised | `/etc/beacon/endpoint/collector.pid` | `~/.beacon/endpoint/collector.pid` |
+Windows has no unit file to point at: the service definition lives in the registry, so that is what
+`beacon endpoint status` reports where the other platforms report a path. And there is no counterpart
+to `systemctl --user` or launchd's per-user domain, so a Windows user-mode install always gets the
+supervised collector — see [Windows install](/platforms/windows#user-mode-install).
+
A supervised collector is a plain background process tracked by a pidfile. It works, but nothing
restarts it if it exits or when the machine reboots — `beacon endpoint status` says so explicitly
rather than reporting the same health as a real service.
diff --git a/docs/contributing/beacon-sandbox.mdx b/docs/contributing/beacon-sandbox.mdx
index 0c295115..3ef909e6 100644
--- a/docs/contributing/beacon-sandbox.mdx
+++ b/docs/contributing/beacon-sandbox.mdx
@@ -219,6 +219,86 @@ background collector when it finds no service manager, and that fallback also re
running — so without naming the backend you expect, a test meant to cover systemd could quietly pass
while covering the fallback instead.
+## Testing The Windows Build
+
+Modal offers Linux machines only, so Windows needs a different disposable machine. It uses a
+GitHub-hosted Windows runner, which is already one: a fresh virtual machine per job, with
+administrator rights, UAC disabled, and a real Service Control Manager — everything an endpoint
+install needs.
+
+The difference from the Linux path is where the sandbox is. On Modal the tool starts a machine and
+drives it from outside. On Windows **the runner is the sandbox**, and the tool runs inside it. The
+collected output is uploaded and judged on your machine afterwards by the same code that judges a
+Modal run, so a Windows verdict is produced by the same rules as a Linux one.
+
+Runner minutes are free on this public repository, so unlike the Linux tests these cost only the
+Anthropic API session.
+
+### Running One
+
+```bash title="Dispatch a Windows test"
+gh workflow run windows-sandbox.yml -f scenario=w03-hook-capture
+gh run watch
+```
+
+Leave `scenario` empty to run every Windows test. Each takes a few minutes; the whole set is about
+fifteen.
+
+| Test | Covers |
+|------|--------|
+| `w00-probe` | The `beacon ci exec` collection path. Known to be unreliable on Windows — see [#320](https://github.com/asymptote-labs/agent-beacon/issues/320) |
+| `w01-install-service` | A system-mode install registered with the Service Control Manager, then a session against it |
+| `w02-install-supervised` | A user-mode install, which falls back to a supervised collector because Windows has no per-user service manager |
+| `w03-hook-capture` | Capture through *installed* hooks: prompts, command text, and file edits |
+| `w04-denied-tool` | Approvals and denials through installed hooks |
+
+`w03` is the one that matters most. It goes through hooks Beacon installed rather than a temporary
+collector, which is what a real user gets — and it is the only test that can tell you the command
+string Beacon writes into a runtime's settings is one that runtime can actually execute.
+
+### Setting It Up
+
+Dispatching needs write access to the repository, plus an `ANTHROPIC_API_KEY` secret in the
+`windows-sandbox` environment. Scoped to an environment rather than the repository, matching how the
+release secrets are handled:
+
+```bash title="Store the key, without it entering your shell history"
+gh api -X PUT repos/asymptote-labs/agent-beacon/environments/windows-sandbox
+printf '%s' "$ANTHROPIC_API_KEY" | gh secret set ANTHROPIC_API_KEY \
+ --repo asymptote-labs/agent-beacon --env windows-sandbox
+```
+
+Use a dedicated, budget-capped key. The harness runs a real agent with
+`--dangerously-skip-permissions`, and the per-session budget in a scenario is a client-side cap
+rather than an account guard.
+
+<Note>
+ The workflow is `workflow_dispatch` only, and deliberately. It needs an API key to run a real
+ session, and on a public repository that secret must never be reachable from a fork's pull request —
+ so there is no `pull_request` trigger and there must never be a `pull_request_target` one.
+</Note>
+
+### One Check Works Differently There
+
+Every Linux run fingerprints your own Beacon state before and after, so a test that accidentally
+installed something on your machine is caught rather than assumed impossible. That comparison only
+means something when the sandbox is a *different* machine.
+
+On Windows it is not — the install being tested is itself the change the guard would report. So the
+run records a different kind of evidence: that the machine is disposable (a GitHub-hosted runner, one
+fresh VM per job). The verdict says which of the two it relied on rather than silently reporting the
+comparison as clean:
+
+```
+[WARN] safety.host_untouched: host isolation was not verified by comparison because the guest
+ was this machine
+ why: isolation is only as good as the machine being disposable
+ (github-hosted ephemeral runner (fresh VM per job))
+```
+
+That warning is expected on every Windows run. It is not a problem to fix; it is the tool declining to
+claim a check it could not perform.
+
## Commands
| Command | What it does |
@@ -276,12 +356,14 @@ go test ./...
## Limitations
<Warning>
- Modal only provides Linux machines, so **this cannot test the macOS build**. Anything macOS-specific — launchd, the signed installer, notarization — is out of reach.
+ **The macOS build cannot be tested this way.** Modal provides Linux machines, and the Windows path
+ above uses a GitHub-hosted Windows runner; neither offers macOS. Anything macOS-specific — launchd,
+ the signed installer, notarization — is out of reach and has to be checked by hand on a Mac.
</Warning>
- **The systemd tests run nested.** `i02` runs inside a container within the sandbox, so it is slower and needs a few more minutes of patience than the others.
- **It checks presence, not completeness.** It confirms the thing it planted was recorded. It cannot tell you whether Beacon missed something it never knew to look for.
-- **Linux x86 only.** Modal does not offer a choice of processor architecture.
+- **Linux x86 only on Modal, x64 only on Windows.** Neither backend offers a choice of processor architecture, so the ARM builds are not covered.
- **It costs money and takes minutes.** Each test is a real API session.
- **Occasional flakiness is normal.** Telemetry arrives asynchronously, so the tool waits for activity to settle rather than a fixed delay. Use `--repeat 3` to tell a flaky result from a broken one.
- **The agent version is pinned.** Claude Code's behaviour changes between releases, so the sandbox installs a fixed version. Updating it is a deliberate change.
diff --git a/docs/docs.json b/docs/docs.json
index d5cc04c7..b01f0e1f 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -291,7 +291,8 @@
"icon": "laptop",
"pages": [
"platforms/macos",
- "platforms/linux"
+ "platforms/linux",
+ "platforms/windows"
]
},
"cli/upgrade",
diff --git a/docs/get-started/quickstart-security-it.mdx b/docs/get-started/quickstart-security-it.mdx
index 3eb3f032..b143a223 100644
--- a/docs/get-started/quickstart-security-it.mdx
+++ b/docs/get-started/quickstart-security-it.mdx
@@ -22,6 +22,7 @@ For the full comparison, see [Hosting Options](/deployment/hosting-options).
If you are starting local-first, pilot Beacon on a small group before broad deployment. The fleet
story differs by platform, so read the one you are rolling out to first:
[macOS](/platforms/macos) ships MDM assets for Jamf, Fleet, and Rippling;
+[Windows](/platforms/windows) ships an MSI for Intune or SCCM;
[Linux](/platforms/linux) ships `.deb` and `.rpm` packages that install and start the endpoint
themselves.
diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx
index 11262607..4726d6f4 100644
--- a/docs/get-started/quickstart.mdx
+++ b/docs/get-started/quickstart.mdx
@@ -58,6 +58,9 @@ package, the service manager, and how a fleet is deployed are not the same on ea
<Card title="Linux" icon="linux" href="/platforms/linux">
A `.deb` or `.rpm` that installs and starts the endpoint for you. systemd.
</Card>
+ <Card title="Windows" icon="windows" href="/platforms/windows">
+ An MSI that installs and starts the endpoint for you. Windows Service Control Manager.
+ </Card>
</Columns>
Capturing from CI jobs, cloud agents, or your own applications through the SDK needs none of this —
diff --git a/docs/platforms/windows.mdx b/docs/platforms/windows.mdx
new file mode 100644
index 00000000..7b9adf13
--- /dev/null
+++ b/docs/platforms/windows.mdx
@@ -0,0 +1,310 @@
+---
+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.
+
+<Warning>
+ **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:
+
+ ```powershell
+ (Get-FileHash BeaconEndpointAgent-<version>-x64.msi -Algorithm SHA256).Hash
+ ```
+
+ Authenticode signing is planned; until then the checksum is the 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
+ 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.
+</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 reports `running=true` too.
+The JSON output names it:
+
+```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, 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:
+
+```
+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 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:
+
+```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
+
+Nothing to remember. 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, 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:
+
+| Path | Carries |
+|---|---|
+| OpenTelemetry | Prompts, tool calls, token usage, cost — via `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, 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
+```
+
+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;
+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:
+
+```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 — 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:
+
+```powershell title="Repair the service"
+beacon endpoint doctor --system --fix
+```
+
+## 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:
+
+```powershell title="User-mode install"
+beacon endpoint 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:
+
+```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
+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.
+
+<Note>
+ `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.
+</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
+
+Stated here rather than left to be discovered:
+
+| Gap | Status |
+|---|---|
+| The installer is unsigned | SmartScreen warns; verify the published `.sha256`. Authenticode signing is planned |
+| `beacon endpoint update --apply` | Not supported on Windows; 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 described on this page is unaffected |
+| User-mode collectors | Do not restart and do not survive sign-out — no per-user service manager exists |
+| 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>