Sync open source content 🐝 (from 79821a6480478f0ba9a762c62ba7b9da0c09c216)

Author: beezythebot

docs/ai-control-plane/reference/device-agent/mdm-installations/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: MDM installations
-description: "Deploy the device agent through your MDM, verify the rollout with agent coverage, and export it as compliance evidence, with guides for Jamf Pro, Iru (formerly Kandji), Intune, Drata, and Vanta."
+description: "Deploy the device agent through your MDM, verify the rollout with agent coverage, and export it as compliance evidence, with guides for Jamf Pro, Iru (formerly Kandji), Intune, Linux, Drata, and Vanta."
 ---
 
 import { Callout, StatusBadge } from "@/mdx/components";
@@ -12,9 +12,13 @@ This page covers the shared concepts. The provider guides cover the console-spec
 
 **Inventory sources** (your MDM: deploy the agent, pull the fleet):
 
-- [Jamf Pro](/docs/ai-control-plane/reference/device-agent/mdm-installations/jamf): deploy and verify (inventory integration supported)
-- [Iru (formerly Kandji)](/docs/ai-control-plane/reference/device-agent/mdm-installations/iru): deploy and verify (inventory integration supported)
-- [Microsoft Intune](/docs/ai-control-plane/reference/device-agent/mdm-installations/intune): deploy and verify (inventory integration supported)
+- [Jamf Pro](/docs/ai-control-plane/reference/device-agent/mdm-installations/jamf): deploy and verify on macOS (inventory integration supported)
+- [Iru (formerly Kandji)](/docs/ai-control-plane/reference/device-agent/mdm-installations/iru): deploy and verify on macOS (inventory integration supported)
+- [Microsoft Intune](/docs/ai-control-plane/reference/device-agent/mdm-installations/intune): deploy and verify on macOS and Windows (inventory integration supported)
+
+Jamf Pro and Iru manage Apple devices only. For the platforms they don't cover:
+
+- [Linux](/docs/ai-control-plane/reference/device-agent/mdm-installations/linux): deploy through Ansible, Puppet, or any configuration management (no inventory integration)
 
 **Evidence destinations** (your compliance platform: push coverage as evidence):
 
@@ -29,44 +33,38 @@ The agent ships as a single Developer ID signed, notarized, universal `.pkg` tha
 
 Upload that file to your MDM as a Package (Jamf), Custom App (Iru), or line-of-business `.pkg` app (Intune) (see the provider guides below for the exact steps) and push it once. With `auto_update: "automatic"` set in the managed configuration below, the agent keeps the daemon, CLI, and app current on its own; re-push the pkg only for a change to the install layout itself, not routine releases.
 
-### Windows and Linux
+### Windows
+
+The agent ships a per-machine, Authenticode-signed `.msi` (`speakeasy-agent_<version>.msi`) that installs the daemon, CLI, and UI under `C:\Program Files\Speakeasy\` and registers the daemon as a LocalSystem service. Download it from the release bucket at `https://storage.googleapis.com/speakeasy-device-agent-releases-prod/v<version>/speakeasy-agent_<version>.msi` and push it as a Win32 app or line-of-business MSI. Raw `.zip` binaries remain available for scripted or air-gapped installs, but they are unsigned. Prefer the MSI.
 
-There's no signed installer package for Windows or Linux yet. Install by downloading the `speakeasyd` daemon and `speakeasy` CLI directly from the public release bucket, then registering the daemon as a background service. This is the same download-and-register flow the **Device Agent** page in the dashboard walks through interactively for a chosen platform, so it doubles as the script to wrap in an MDM policy.
+Windows cannot self-update, because the OS locks running executables, so version moves are an MSI re-push and `auto_update` must stay on `"notify"` rather than `"automatic"` on an MSI fleet. See [Microsoft Intune](/docs/ai-control-plane/reference/device-agent/mdm-installations/intune#windows) for the full recipe, including the detection rule, the `%ProgramData%` ACL grant, and the service-restart requirement.
 
-**Linux:**
+### Linux
+
+There is no installer package for the Linux daemon. Install by downloading the `speakeasyd` daemon and `speakeasy` CLI from the release bucket, then registering the systemd unit:
 
 ```bash
 VERSION=$(curl -s https://storage.googleapis.com/speakeasy-device-agent-releases-prod/releases.json | jq -r '.latest.speakeasyd.version')
 BASE=https://storage.googleapis.com/speakeasy-device-agent-releases-prod/v$VERSION
-curl -fSL -o speakeasyd "$BASE/speakeasyd_${VERSION}_linux_amd64"
-curl -fSL -o speakeasy  "$BASE/speakeasy_${VERSION}_linux_amd64"
-chmod +x speakeasyd speakeasy
-sudo mv speakeasyd speakeasy /usr/local/bin/
+ARCH=amd64  # or arm64
+
+sudo curl -fSL -o /usr/local/bin/speakeasyd "$BASE/speakeasyd_${VERSION}_linux_${ARCH}"
+sudo curl -fSL -o /usr/local/bin/speakeasy  "$BASE/speakeasy_${VERSION}_linux_${ARCH}"
+sudo chmod 0755 /usr/local/bin/speakeasyd /usr/local/bin/speakeasy
 
-speakeasyd -service install
+speakeasyd -service install   # as the user, not root
 speakeasyd -service start
-speakeasyd status
+speakeasy status
 ```
 
-Swap `linux_amd64` for `linux_arm64` on ARM. `-service install` registers `speakeasyd` as a systemd service so it survives reboots and re-logins.
-
-**Windows (PowerShell):**
-
-```powershell
-$VERSION = (Invoke-RestMethod https://storage.googleapis.com/speakeasy-device-agent-releases-prod/releases.json).latest.speakeasyd.version
-$BASE = "https://storage.googleapis.com/speakeasy-device-agent-releases-prod/v$VERSION"
-Invoke-WebRequest "$BASE/speakeasyd_${VERSION}_windows_amd64.exe" -OutFile speakeasyd.exe
-Invoke-WebRequest "$BASE/speakeasy_${VERSION}_windows_amd64.exe"  -OutFile speakeasy.exe
-
-.\speakeasyd.exe -service install
-.\speakeasyd.exe -service start
-.\speakeasy.exe status
-```
+<Callout type="warning">
+  The Linux daemon registers a **per-user** systemd unit (`~/.config/systemd/user/com.speakeasy.daemon.service`), so `-service install` must run in each user's own session. Running it under `sudo` installs the unit for root, which has no user identity to attribute sessions to. On headless machines, `sudo loginctl enable-linger <user>` is also required, or the user unit never starts.
+</Callout>
 
-There's no chmod or move step on Windows: run the `.exe` files in place, or copy them onto `PATH` yourself. `-service install` registers `speakeasyd` as a Windows service.
+The [Linux guide](/docs/ai-control-plane/reference/device-agent/mdm-installations/linux) covers the full config-management rollout, including the root helper package that unlocks managed-layer enforcement.
 
 <Callout type="info">
-  For a fleet, wrap these downloads and the `-service install` / `-service start` commands in your MDM's script or Win32-app mechanism instead of running them by hand on every machine (see the Windows section of [Microsoft Intune](/docs/ai-control-plane/reference/device-agent/mdm-installations/intune#windows)). For a single device, the same commands work from an interactive shell, or use the guided walkthrough on the **Device Agent** page in the dashboard, which fills in the current version and lets you download the binaries directly instead of scripting it.
+  For a fleet, wrap these steps in the mechanism your configuration management or MDM provides rather than running them by hand on every machine. For a single device, the same commands work from an interactive shell, or use the guided walkthrough on the **Device Agent** page in the dashboard, which fills in the current version and lets you download the binaries directly instead of scripting it.
 </Callout>
 
 Once the daemon is running, set the device's identity the same way as macOS: deploy [the managed configuration](#the-managed-configuration) below for a fleet, or run `speakeasy enroll` for a one-off or personal install.
@@ -125,7 +123,7 @@ The configuration must be readable by the logged-in user, not just root: the age
 
 ### Updating the managed configuration
 
-The agent reads its configuration at daemon startup, not continuously, so a change to the file or profile doesn't take effect until the daemon restarts. Any policy that writes the file must restart the daemon afterwards, on every run: a rotated token sits inert on disk until the next restart. The same restart rule applies to profile updates. On a pkg-installed macOS device, restart the console user's LaunchAgent (`launchctl kickstart -k "gui/$(id -u)/com.speakeasy.daemon"`), substituting the console user's uid when run from a root MDM policy. Linux and Windows service installs still use `speakeasyd -service restart`.
+The agent reads its configuration at daemon startup, not continuously, so a change to the file or profile doesn't take effect until the daemon restarts. Any policy that writes the file must restart the daemon afterwards, on every run: a rotated token sits inert on disk until the next restart. The same restart rule applies to profile updates. On a pkg-installed macOS device, restart the console user's LaunchAgent (`launchctl kickstart -k "gui/$(id -u)/com.speakeasy.daemon"`), substituting the console user's uid when run from a root MDM policy. Windows service installs use `speakeasyd -service restart` (or `sc stop`/`sc start`). Linux uses the same command, but it must run in the user's own session, since the unit is per-user.
 
 ## Verify the rollout with agent coverage
 

docs/ai-control-plane/reference/device-agent/mdm-installations/intune.mdx

@@ -1,9 +1,11 @@
 ---
 title: "Microsoft Intune"
-description: "Deploy the device agent with Microsoft Intune on macOS and Windows."
+description: "Deploy the device agent with Microsoft Intune on macOS, Windows, and Linux, and connect the tenant to the dashboard for agent coverage."
 ---
 
-Intune deploys the device agent's managed configuration on both macOS and Windows. Shared concepts (the configuration schema, delivery channels, and coverage states) are on the [MDM installations](/docs/ai-control-plane/reference/device-agent/mdm-installations) page.
+import { Callout } from "@/mdx/components";
+
+Intune deploys the device agent and its managed configuration on macOS, Windows, and Linux. Shared concepts (the configuration schema, delivery channels, and coverage states) are on the [MDM installations](/docs/ai-control-plane/reference/device-agent/mdm-installations) page.
 
 ## macOS
 
@@ -15,7 +17,65 @@ Intune deploys the device agent's managed configuration on both macOS and Window
 
 ## Windows
 
-Use **Devices → Scripts** (PowerShell) or a packaged Win32 app that drops `managed.json` under `%ProgramData%\Speakeasy\`, with an ACL granting the logged-in user read access (the agent runs as that user and only reads the file).
+The agent ships a per-machine `.msi` that installs the daemon, CLI, and UI under `C:\Program Files\Speakeasy\` and registers the daemon as a LocalSystem service. The MSI and every executable inside it are Authenticode-signed. Prefer it over the raw binaries: it handles service registration and upgrades, and it sidesteps the SmartScreen warnings that unsigned `.zip` downloads attract.
+
+<Callout type="info">
+  The Windows service model differs from macOS in a way worth planning around. The daemon runs machine-wide as **LocalSystem**, not per-user, so standard users cannot stop it (better tamper resistance than the macOS Login Items toggle) while local admins can. Tool syncing still targets the **active console user's** home (`~/.claude`, `~/.cursor`, `~/.codex`); with nobody signed in, the daemon idles rather than writing into the SYSTEM profile.
+</Callout>
+
+**Install the agent.** Download `speakeasy-agent_<version>.msi` from the release bucket (`https://storage.googleapis.com/speakeasy-device-agent-releases-prod/v<version>/speakeasy-agent_<version>.msi`) and add it as a **Win32 app** or line-of-business MSI under **Devices → Apps**.
+
+- Install command: `msiexec /i speakeasy-agent_<version>.msi /qn /norestart`
+- Detection: the product UpgradeCode `368ec0a6-8862-4906-af34-8c3adb92c6e0`, or the presence of `C:\Program Files\Speakeasy\speakeasyd.exe`
+
+**Deploy the managed configuration separately.** Use **Devices → Scripts** (PowerShell) or a second Win32 payload to write `%ProgramData%\Speakeasy\managed.json`. The MSI creates that directory with a Users-read ACL already in place. The file must stay readable by the logged-in user, because the daemon resolves the console user's identity from it:
+
+```powershell
+$dir = "$env:ProgramData\Speakeasy"
+New-Item -ItemType Directory -Force -Path $dir | Out-Null
+Set-Content -Path "$dir\managed.json" -Encoding UTF8 -Value @"
+{
+  "v": 1,
+  "email": "jane.doe@example.com",
+  "org_token": "$OrgToken",
+  "org_slug": "example-corp",
+  "auto_update": "notify"
+}
+"@
+icacls $dir /grant "BUILTIN\Users:(OI)(CI)R"
+
+& "$env:ProgramFiles\Speakeasy\speakeasyd.exe" -service restart
+```
+
+Restarting the service on **every** script run is not optional: the daemon reads its configuration at startup, so a rotated token sits inert on disk until the service restarts. Leave "run script only once" off, and pass the `org_token` as a script parameter rather than a literal in the script body. `sc stop com.speakeasy.daemon && sc start com.speakeasy.daemon` works as an alternative to `-service restart`.
+
+<Callout type="warning">
+  Do not tighten the `%ProgramData%\Speakeasy` ACL to SYSTEM-only. That is the Windows form of the `0600` trap and it silently breaks enrollment.
+</Callout>
+
+**Version moves are an MSI re-push.** Windows locks running executables, so `speakeasy update --apply` is not supported there and `auto_update` must not be set to `"automatic"` on an MSI fleet: the updater cannot replace a running LocalSystem executable under Program Files. Keep it on `"notify"` so devices still learn about the per-version kill switch, and push the newer MSI to move versions. Its MajorUpgrade stops the service, replaces the files, and starts it again, leaving no orphaned service entry.
+
+**The menu bar UI is installed but not started.** The MSI lays down `speakeasy-ui.exe` without auto-starting it, matching the posture on every other OS. Deploy a Startup shortcut to `C:\Program Files\Speakeasy\speakeasy-ui.exe` if the fleet wants the tray icon. The daemon is fully functional without it.
+
+**Managed-layer enforcement needs nothing extra.** Because the Windows daemon already runs as LocalSystem, it performs privileged writes in-process rather than through a separate root helper as macOS and Linux do. Setting a tool to `"managed"` lands its system configuration on the first reconcile, with no `EnforcementPending` window waiting on a package: `%ProgramData%\OpenAI\Codex\requirements.toml` (Codex), `%ProgramData%\Cursor\hooks.json` (Cursor), and `%ProgramData%\ClaudeCode\managed-settings.json` (Claude Code). Each is written SYSTEM-owned with a protected ACL (SYSTEM and Administrators full, Users read-only), the Windows equivalent of a root-owned `0644`.
+
+<Callout type="info">
+  Daemon logs land in the SYSTEM profile when the agent runs as a service: `C:\Windows\System32\config\systemprofile\AppData\Local\Speakeasy\Logs\`. Run interactively, they go to `%LOCALAPPDATA%\Speakeasy\Logs\` instead. Worth telling the support desk before they go hunting.
+</Callout>
+
+### Scripted install without the MSI
+
+Still valid for an air-gapped mirror or a custom install layout: resolve the version, URL, and SHA-256 from the release manifest (never hardcode them), place the binaries under `C:\Program Files\Speakeasy\`, then run `speakeasyd -service install` followed by `-service start`. Write `managed.json` with the same ACL grant as above, restart the service on every run, and move versions by stopping the service, replacing the binaries, and starting it again. Note that the raw `.zip` binaries are not signed, so browser downloads of them may draw a SmartScreen warning; Intune line-of-business installs are unaffected.
+
+## Linux
+
+Intune's Linux support covers a narrow set of distributions and its script mechanism runs as root, which does not match how the agent registers itself. The daemon installs a **per-user** systemd unit, so the `-service install` step has to run in each user's own session rather than from a root policy.
+
+An Intune-driven rollout can still place the binaries and write `/etc/speakeasy/managed.json` as `root:root` `0644`. Registering and starting the unit is the part that needs a per-user mechanism, and most Linux fleets are better served by the configuration management already running on them. See the [Linux guide](/docs/ai-control-plane/reference/device-agent/mdm-installations/linux) for the full sequence, including the lingering requirement on headless machines and the root helper package that unlocks managed-layer enforcement.
+
+<Callout type="info">
+  Intune has no supported inventory source for Linux devices in the dashboard, so Linux coverage is attested through [Employee Enrollment](/docs/ai-control-plane/observe/employee-enrollment) rather than the fleet-wide managed-device view. The Intune inventory sync below covers macOS and Windows devices.
+</Callout>
 
 ## Connect Intune to the dashboard