Skip to main content
This guide takes you from no Beacon on your Windows desktops to every machine in a Configuration Manager (ConfigMgr, formerly SCCM) pilot collection recording its AI agent activity, attributed to the person who ran the agent. Follow the steps in order.

What you’ll set up

When you finish, each machine in the pilot has:
  • Beacon installed from the MSI, with its collector running as the BeaconCollector Windows service.
  • The fleet settings you chose, read from HKLM\SOFTWARE\Policies\Beacon\Endpoint on every install and upgrade.
  • Claude Code and Codex reporting to that collector, for each person who signs in.
  • Agent activity written to C:\ProgramData\Beacon\Endpoint\logs\runtime.jsonl, which only SYSTEM, Administrators and the beacon-log group can read.
You create two applications: To send the log on to a SIEM, add a forwarder after this guide; see Log forwarding. The Workspace ONE and Microsoft Sentinel guide shows the Sentinel forwarder script, which runs the same way from a ConfigMgr application or script.

Before you start

There is no Windows ARM package. Scope the device collection to x64 machines, or add an operating system requirement to the deployment type. Check the PowerShell execution policy on a pilot machine with Get-ExecutionPolicy -List. The MSI installs, upgrades and removes Beacon by running PowerShell scripts that are not signed yet, so it cannot run where Group Policy sets MachinePolicy to AllSigned or Restricted. On those machines the device application fails and nothing is installed, and a machine that already has Beacon keeps running it but cannot upgrade or remove it. Any other MachinePolicy value, including Undefined, is fine.

1. Prepare the content

Download BeaconEndpointAgent-<version>-x64.msi and its .sha256 from the releases page and check it. The package is not code-signed yet, so the checksum is the only integrity check it has:
Make one content folder per release, for example \\cm01\Sources\Beacon\<version>\, and put the MSI there with this script, saved as install-beacon.ps1:
install-beacon.ps1
The MSI cannot take environment variables from Configuration Manager, so its install step reads these settings as policy values instead. Writing them in the same script as the install guarantees they are there first. Change the values to suit your fleet: The full list of settings is in Fleet deployment. If you already manage registry values with Group Policy, you can set the same values with a Group Policy registry preference instead and keep only the msiexec part of the script. Make sure the policy applies before the application installs; the values are read only when the MSI runs. Keep /norestart. The package never needs a reboot, and without it Windows Installer can restart the machine on its own if something holds a file it has to replace.

2. Create the device application

In the Configuration Manager console, go to Software Library > Application Management > Applications and choose Create Application.
  1. Choose Windows Installer (*.msi file) and select the MSI in the content folder. The wizard reads the product code and fills in the detection method and uninstall program from it.
  2. Name it Beacon Endpoint Agent <version>.
  3. On General Information, change Installation program to:
    Set Install behavior to Install for system.
  4. Finish the wizard, then open the deployment type’s properties and check these settings: Leave the return codes at their defaults. The script passes on the code msiexec exits with.
  5. Distribute the content to your distribution points, then deploy the application to the pilot device collection with Purpose: Required.
Every release has its own product code, so detection matches only the exact version you deployed. The MSI configures the agent tools of whoever is signed in at the console when it installs. Machines that install with nobody signed in, and other people who sign in later, are covered by step 3. If you run AppLocker or Windows Defender Application Control, allow by path or file hash, since nothing here is code-signed yet:
  • the MSI itself, and install-beacon.ps1;
  • beacon.exe, beacon-hooks.exe, beacon-otelcol.exe and vector.exe in C:\Program Files\Beacon\bin;
  • the package’s PowerShell scripts in C:\Program Files\Beacon\scripts, which the MSI runs as SYSTEM;
  • the copy of the hook program agents run from each profile, %USERPROFILE%\.beacon\endpoint\hooks\beacon-hooks.exe;
  • configure-agent-tools.ps1 from step 3.
Success looks like: the deployment reports success in Monitoring > Deployments, and on the machine sc.exe query BeaconCollector reports RUNNING.

3. Create the per-user application

Each person’s Claude Code and Codex settings live in their own profile, so this step runs as each person who signs in. Save this script as configure-agent-tools.ps1 in its own content folder, for example \\cm01\Sources\Beacon\agent-tools\:
configure-agent-tools.ps1
Use the same runtimes in --harness as in BEACON_ENDPOINT_HARNESSES. Create a second application, this time choosing Manually specify the application information, with a Script Installer deployment type:
Detection script
Configuration Manager runs detection scripts under the client setting Computer Agent > PowerShell execution policy, which is All Signed by default and rejects this unsigned script. Set it to Bypass in the client settings deployed to the pilot machines, or sign the script. The installation programs pass -ExecutionPolicy Bypass themselves, but an execution policy set by Group Policy overrides that too, so check for one if either script never runs. Deploy it to the pilot user collection with Purpose: Required. Configuration Manager then runs it once for each person when they sign in to a machine, including people who were not signed in when Beacon was installed. Until the device application has installed Beacon, the script fails, and Configuration Manager tries again at its next evaluation. The hooks it installs run as that person, so their events carry the person’s Windows account (their SID), which is how every event is attributed on a machine several people use. Success looks like: the deployment reports success for the user, and %USERPROFILE%\.claude\settings.json contains OTEL_EXPORTER_OTLP_ENDPOINT and Beacon’s hooks.

4. Check one machine

From an elevated PowerShell on a pilot machine:
Expect log_access to be restricted, dashboard to be disabled, and runtime_log_access: ok from doctor. Then have someone send one prompt in Claude Code or Codex, and look at the newest events:
The person’s account should appear, not the machine account (COMPUTERNAME$).

Upgrades and removal

Beacon never updates itself, so the version on each machine is the one you deploy.
  • Upgrade: make a content folder for the new release with its MSI and the same install-beacon.ps1, and create a new application from it as in step 2. On the new application, add a supersedence of the previous one, and leave Uninstall unchecked: the MSI removes the older version itself during the upgrade, keeping the endpoint’s configuration, log access mode and beacon-log members, and reading the policy values again. Deploy the new application to the same collection. There is a short gap with no collector while the old one is replaced.
  • Uninstall: deploy the application with Action: Uninstall. Removal stops and deletes the service and the program files, but leaves C:\ProgramData\Beacon\Endpoint, including the log. To remove that too, see Uninstall.
  • Roll back: the MSI refuses to install over a newer version. Uninstall the newer application first, then deploy the older one.
The per-user application needs no change for an upgrade. If you change --harness, rename the marker file in both scripts (for example configmgr-agent-tools-2) so the application runs again for everyone.

Troubleshooting

See Windows install for the install logs, time limits and what the install changes on the machine.

Fleet deployment

Every fleet setting, version pinning, and how to check a machine.

Windows install

The MSI, the service, and how upgrades and uninstall work.

Restricted log access

Who can read and write the runtime log.

Log forwarding

Send Beacon events to your SIEM or a customer-managed pipeline.