# Crayonic Agent - Deployment and Settings (AD / Group Policy Guide) This guide is for administrators who install the Crayonic Agent on many machines and who configure it with Group Policy instead of, or without, the Crayonic Device Manager (CDM). Installation can be from the installer command line, Group Policy, SCCM/MECM or Intune. ## Deliverables - MSI package: `CrayonicAgent_x64_1.0.633.msi` - Transform (MST) that installs it with Cloud Sync off: `CrayonicAgent_x64_1.0.633_CloudSyncDisabled.mst` On each machine the agent also installs **Start menu > Crayonic > Crayonic - Agent Settings**. This settings window sets up badge sign-in, shows the bridge and badges, and installs bridge firmware and agent updates. It also exports the settings for other machines. ## Cloud Sync With Cloud Sync off, the agent sends nothing to CDM and nothing to crash.crayonic.io: - No events, no start-up event and no heartbeat. - No MQTT connection, so CDM cannot reach the machine: no commands and no log collection. The MQTT switches in a settings document have no effect. - No settings requests. The agent's settings come only from the machine's settings document, the Group Policy one (see "Agent settings without CDM") and any "Apply until restart" change made in the settings window. - No crash reports. A bridge or badge keeps its last crash record until Cloud Sync is on again, unless it loses power or a bridge firmware update runs. Bridge, badge and sign-in functions keep working. Agent and bridge firmware updates still download from release.crayonic.io, as the update policies in those documents say. With no update policy, the agent installs the newest build of its STABLE channel and the bridge firmware stays where it is (see "Updates in production"). No firewall rule is needed. An update policy whose `channel_url` points at CDM's release proxy (`/release/...`) gets no updates while Cloud Sync is off, because the proxy is part of CDM. A document exported with `--from effective` carries that URL if CDM used it, so change it to release.crayonic.io before delivering the document. On a machine CDM configured, turning Cloud Sync off drops CDM's settings within seconds: - Agent updates follow the newest STABLE build, unless a document states an update policy. - Bridge firmware is held. - Badge sign-in set up by CDM stops at the next restart of the agent. On a machine whose agent is older than the newest STABLE build, the update in the first point causes that restart within minutes. - Badge firmware updates stop: only CDM rolls them out. To keep the machine as CDM set it up, export its settings with `--from effective` first (see "Agent settings without CDM") and deliver them as the machine or Group Policy document. Events recorded while Cloud Sync is off stay on the machine and are never uploaded, not even after Cloud Sync is turned back on. The same goes for events still waiting for upload when it goes off, and for those an older agent left waiting, once this agent has started with Cloud Sync off. (If the upgrade from 1.0.623 or earlier and turning Cloud Sync on reach a machine together, the older agent's backlog is uploaded.) They are deleted with the rest of the local history after 30 days. The agent's log files are different: if CDM collects logs or runs diagnostics once Cloud Sync is on again, the logs and the recent warnings go as they are, off period included. The agent rereads `CloudSyncEnabled` every few seconds, so no restart is needed: - Turned off: it takes effect at the next reading, within about 5 seconds, with no second reading needed. The agent closes its MQTT connection without sending anything, and CDM shows the machine offline. It drops the settings CDM delivered and keeps the machine and Group Policy documents and any "Apply until restart" change. - Turned on: it takes effect when a second reading, a few seconds later, still says on. The agent then checks in with CDM as it does at a service start. With Cloud Sync on, a machine that CDM does not manage gets CDM's defaults: the newest STABLE agent, bridge firmware held, and every sign-in setting off. A settings document on the machine (below) wins over those. ## Install from the command line Installer properties: - **CLOUDSYNCENABLED**: `0` turns Cloud Sync off; `1`, the default, turns it on. - **CLOUDSYNCURL**: optional custom URL for the Cloud Sync endpoint. ```batch REM Cloud Sync on (default) msiexec /i "CrayonicAgent_x64_1.0.633.msi" /qn REM Cloud Sync off msiexec /i "CrayonicAgent_x64_1.0.633.msi" CLOUDSYNCENABLED=0 /qn REM Cloud Sync off, using the transform instead of a property msiexec /i "CrayonicAgent_x64_1.0.633.msi" TRANSFORMS="CrayonicAgent_x64_1.0.633_CloudSyncDisabled.mst" /qn REM Custom Cloud Sync URL msiexec /i "CrayonicAgent_x64_1.0.633.msi" CLOUDSYNCURL=https://internal.company.example /qn ``` The installer properties and the MST only affect machines that do not already have these values. A later install, repair or upgrade never overwrites the values they wrote. To change an existing fleet, set the policy values described under "Cloud Sync settings in the registry" instead. ## Install with Group Policy (Software installation) Prerequisites: - Put the MSI and the MST on a UNC share that computer accounts can read, for example `\\fileserver\software\Crayonic\`. - Give Domain Computers read access to the share. - Keep both files at that path for as long as the GPO deploys them. Steps: 1. Open Group Policy Management (GPMC) and create or edit a GPO linked to the target OU. 2. Go to **Computer Configuration > Policies > Software Settings > Software installation**. 3. Right-click **Software installation > New > Package...** and select the MSI by its UNC path, not a mapped drive. 4. Choose **Advanced**. On the **Modifications** tab, click **Add...** and select the MST from the same share. Do this before you click OK, because a transform cannot be added after the package is deployed. 5. **Deployment** tab: leave the deployment type as **Assigned**. Computers can only be assigned. 6. Optional: on the **Upgrades** tab, set the package to upgrade earlier versions of the agent. Notes: - Group Policy Software installation has no field for installer properties, so use the MST. Alternatively, set `CloudSyncEnabled = 0` as a policy value (see below), which also covers machines that already have the agent. - The agent installs at the next **computer startup**, not on a background policy refresh. Run `gpupdate /force` and restart the computer. - With Fast Logon Optimization it can take two restarts. That is unless **Computer Configuration > Administrative Templates > System > Logon > Always wait for the network at computer startup and logon** is enabled. - To check the install: - Run `gpresult /r /scope computer` in an elevated prompt. - In the System log, Application Management event 302 means installed and 308 means changes applied. - In the Application log, look for MsiInstaller events 11707 and 1033. ## Install with SCCM/MECM or Intune - **SCCM/MECM:** create an Application with an MSI deployment type. The install command is `msiexec /i "CrayonicAgent_x64_1.0.633.msi" /qn`, adding `CLOUDSYNCENABLED=0` or `TRANSFORMS=...` as needed. - **Intune:** create a Win32 app (IntuneWin) that contains the MSI and the MST, with the same install command. - **Detection (both):** use a file rule on `%ProgramFiles%\CrayonicAgent\CrayonicAgentService.exe` with version greater than or equal to `1.0.633.0`. Do not associate it with a 32-bit app on 64-bit clients. - Do not detect by ProductCode. Every build has its own ProductCode and the agent updates itself, so a ProductCode rule turns false after the first self-update. - The deployment would then re-run the older MSI, which refuses to downgrade (exit 1603), and retry forever. ## Cloud Sync settings in the registry The agent reads these keys, highest precedence first: 1. `HKLM\SOFTWARE\Policies\Crayonic\Agent`, set by Group Policy or MDM: - `CloudSyncEnabled` (REG_DWORD): 1 or 0. - `CloudSyncUrl` (REG_SZ): optional URL override. 2. `HKLM\SOFTWARE\Crayonic\Agent`, the local values the MSI writes. It has the same value names. `CloudSyncEnabled` is also read as REG_QWORD, as REG_SZ ("0"/"1", "false"/"true", "off"/"on", "no"/"yes"), or as a REG_BINARY of up to 8 bytes (hex:01, hex:01,00,00,00), which a Group Policy Preferences item or a .reg file may write. Any non-zero number turns Cloud Sync on. A value of any other form, such as an empty string, turns it **off**; the agent does not fall back to the next key. A value that cannot be read turns it off after 30 seconds, or at once while the service is starting; events are not withheld for good over a value that cannot be read. With no value in either key, Cloud Sync is on. The MSI never writes to the Policies key. The MSI also writes `LogLevel` (REG_SZ). It is kept for compatibility only: the service does not read it and always logs at INFO. To raise one machine to DEBUG for a while, use CDM's set_log_level command. ### Setting them with PowerShell Open the key if it exists, and create it only if it does not. Do **not** run `New-Item -Force` on these keys: on an existing key it recreates the key empty. That deletes every value under it, including CloudSyncUrl and the agent's settings document. ```powershell $k = 'HKLM:\SOFTWARE\Policies\Crayonic\Agent' if (-not (Test-Path $k)) { New-Item -Path $k -Force | Out-Null } New-ItemProperty -Path $k -Name 'CloudSyncEnabled' -PropertyType DWord -Value 0 -Force | Out-Null # Optional URL override New-ItemProperty -Path $k -Name 'CloudSyncUrl' -PropertyType String -Value 'https://your-endpoint.example' -Force | Out-Null ``` For a machine's own values, use the same commands with `$k = 'HKLM:\SOFTWARE\Crayonic\Agent'`. This is not recommended as enterprise enforcement. From Intune, run these as SYSTEM in 64-bit PowerShell. A 32-bit host writes `HKLM:\SOFTWARE\Crayonic` into `WOW6432Node`, where the agent never looks. The Policies key is not affected by this. ## Agent settings without CDM (EffectiveSettings) The machine-level settings CDM sets can also be delivered as one JSON document in one REG_SZ value: - `bridge_settings`: bridge mode and the RSSI distances. - `credential_provider`: badge sign-in. - `fw_policy`: bridge firmware updates. - `agent_update_policy`: agent updates. - the two `machine_settings.mqtt` switches, `settings_push` and `event_ingestion`. Badge firmware updates are rolled out by CDM only and cannot be set here. The agent ignores any other section. | Value | Set by | Precedence | |---|---|---| | `HKLM\SOFTWARE\Policies\Crayonic\Agent\EffectiveSettings` | Group Policy, MDM, scripts | Wins over CDM and the machine's own value | | `HKLM\SOFTWARE\Crayonic\Agent\EffectiveSettings` | the settings window ("Save on this machine"), `--import` | Wins over CDM | The agent notices a change within a minute; no restart is needed. Agents from 1.0.589 read these values; the export and the rules below need 1.0.623 or later. What the agent cannot use is reported, never guessed: - A document that is not valid JSON, or not an object, is **refused** whole: `--settings --terminal-only` prints `REFUSED -` with the line and column, and the window shows it in red. - A value it cannot use (a misspelt key, a bridge threshold outside -100..0, a section of the wrong shape) is left out and named on an `!` line, while the rest applies. - While a document cannot be read for an update policy (refused, not an object, the policy in the wrong shape, or a misspelt section name), agent and bridge firmware updates are **held**, whatever CDM says, until it is fixed or a readable document states the policy. - In a document's `agent_update_policy` or `fw_policy`, any of these holds that update (agent or bridge firmware) instead of falling through to CDM's policy or the newest build: - a key other than `mode`, `target_version` and `channel_url` (`"Mode"`, `"mode "`, `"target_verison"`); it is also named on an `!` line; - `"mode": "pinned"` with no `target_version` in force; - a mode the monitor does not know (`"Hold"`, `"pin"`; `"pilot"` is the agent's only); - a `target_version` with no `mode`, while the mode in force is not `pinned`. - A document that sets only `channel_url` keeps CDM's mode as the monitors read it: for the agent, CDM's own `"pinned"` without a version still follows the channel; the bridge firmware monitor holds on a `"pinned"` without a version, with or without the document. - `--import` refuses (exit code 1) a document whose update policy names a key other than those three, instead of storing the rest of it. ### 1. Make the document on one machine 1. Open **Crayonic - Agent Settings**. 2. On the **Setup** tab, choose the **Sign-in method** and click **Apply the smartcard sign-in preset** or **Apply the Entra FIDO sign-in preset** (see "Badge sign-in presets" below). 3. Click **Pin updates to the installed versions** (see "Updates in production" below). 4. Adjust anything else on the other tabs and click **Save on this machine**. 5. Click **Export for Group Policy...**, then either: - **Copy as one line**, or - save the document as a `.reg` file, a Group Policy Preferences item (`.xml`), a PowerShell script that writes the value (`.ps1`), a PowerShell script that adds the item to a GPO, or readable JSON. From an elevated command prompt, the same export is: ```batch "%ProgramFiles%\CrayonicAgent\CrayonicAgentService.exe" --settings --export C:\Temp\crayonic-settings.txt ``` The file's extension picks the form: `.txt` (one line), `.reg`, `.xml`, `.ps1` or `.json`. - `--format gpo` writes the GPO script. A `.ps1` without it is the script that writes the value on the machine it runs on. - `--to machine` targets the machine's own value instead of the Policies key. - `--from effective` exports everything in force, CDM included. - `--settings --help` lists every option. ### Running the command line from scripts `CrayonicAgentService.exe` is a Windows (GUI) program. - A batch file (`.cmd`) waits for it and gets its exit code in `%ERRORLEVEL%`. - PowerShell does **not** wait. A plain `& $exe ...` returns at once and leaves `$LASTEXITCODE` unset, and redirecting the output does not change that. - In PowerShell, start it with `Start-Process -Wait -PassThru`. Build the path from `$env:ProgramW6432`: in a 32-bit PowerShell (Intune's default) `$env:ProgramFiles` is `C:\Program Files (x86)`, where the agent is not. ```powershell $exe = Join-Path $env:ProgramW6432 'CrayonicAgent\CrayonicAgentService.exe' if (-not (Test-Path -LiteralPath $exe)) { 'Crayonic agent is not installed'; exit 1 } $p = Start-Process -FilePath $exe -ArgumentList '--settings','--remove-old-provider' -Wait -PassThru -NoNewWindow -ErrorAction Stop exit $p.ExitCode ``` A path with spaces in `-ArgumentList` needs its own quotes, for example `'--import','"C:\My Files\crayonic-settings.json"'`. ### 2a. Deliver it with Group Policy Preferences 1. In the Group Policy Management Editor, go to **Computer Configuration > Preferences > Windows Settings > Registry > New > Registry Item**, and fill it in: | Field | Value | |---|---| | Action | **Update** | | Hive | `HKEY_LOCAL_MACHINE` | | Key Path | `SOFTWARE\Policies\Crayonic\Agent` | | Value name | `EffectiveSettings` | | Value type | `REG_SZ` | | Value data | the line you copied | 2. Paste **one line**. The Value data box keeps only the text before the first line break, and the agent refuses the incomplete document. The exported line also escapes `%`, `<` and `>`, because Preferences expands `%NAME%` in Value data. 3. Instead of filling the item in by hand, you can do either of these: - Copy the saved `.xml` file in Explorer, then right-click the **Registry** node and choose **Paste**. - On a machine with the Group Policy Management tools, run the saved GPO script: `.\crayonic-gpo.ps1 -GpoName ""`. If the GPO already has a registry item for this value, the script stops and says so. `-Replace` then replaces **every** item for this value in that GPO, hand-made ones included, and does not carry over their item-level targeting or Common-tab options. Use the Policies key for Group Policy. A Group Policy item for the machine's own key (`--to machine`) rewrites that value at every refresh, undoing anything saved on the machine. **A refused document is urgent.** The item writes the same single value, so a refused new document also replaces the previous good one. Updates are held (above), but nothing else of the document applies: - On a machine whose start-up event reaches CDM, CDM's settings take over within about a minute. For a machine CDM does not manage, that switches badge sign-in off. - On a machine that cannot reach CDM, running agents carry on, but after the agent's next restart badge sign-in is gone: the logon screen shows a placeholder instead of badge tiles. **Changing and retiring the document:** - Removing the document does not undo what it set up on the bridges: they keep the last values written to them, unless CDM or the machine's own document states other values. - Removing it takes its update pins with it: with no update policy anywhere, the agent follows the newest STABLE build again and installs it, if it is newer, within a few minutes. - After that restart, or any other restart, the agent no longer serves badge sign-in while the logon screen is still configured to use it. Badge tiles are then replaced by a placeholder. So never delete the value while you want updates pinned or badge sign-in on: - To switch badge sign-in off, deliver a document with `"credprov_enabled": false` that keeps the update policies. Leaving that document in place is the simplest end state. - Any replacement document must keep `agent_update_policy` and `fw_policy`, and the `credential_provider` section for as long as badge sign-in is wanted. When you do retire the item, change its action to **Delete** and leave it in the GPO; each refresh then deletes the value. - Ticking **Remove this item when it is no longer applied** removes nothing by itself. It switches the item to Replace, which rewrites the value at every refresh while the item applies. - The value is deleted only after the item stops applying, and only on machines that applied the ticked item before that. So if you use it, wait until every machine has refreshed policy before you delete the item or unlink the GPO. Either way, delete the **value**, never the key: the Policies key also holds CloudSyncEnabled and CloudSyncUrl. Group Policy files are readable by every computer in the domain. Do not put secrets in the document. ### 2b. Without a domain - **Registry file:** run `reg import crayonic-settings.reg /reg:64` as an administrator. - Without `/reg:64`, a 32-bit runner (an Intune Win32 app install command, for example) writes a `--to machine` export into `WOW6432Node`, where the agent never looks, and still reports success. - `reg import` also reports success for a line it skipped, so check the result with `--settings --terminal-only` (below). - **PowerShell script:** run the exported `.ps1` as SYSTEM or as an administrator, for example as an Intune platform script with "Run this script using the logged on credentials" set to **No**. The script writes the 64-bit registry itself, reads the value back, and exits 0 or 1. It takes no arguments; run anything else, such as the old provider's removal, from a script of its own. - **JSON document:** to save a `.json` export as a machine's own settings, run `CrayonicAgentService.exe --settings --import C:\Temp\crayonic-settings.json`. From PowerShell, run it as shown under "Running the command line from scripts". ### 3. Check a machine - `"%ProgramFiles%\CrayonicAgent\CrayonicAgentService.exe" --settings --terminal-only` prints the layers. The `Group Policy` line names the sections the policy sets, or says `REFUSED -` with the reason; `!` lines name what was left out. - The settings window shows the same in its banner and on the Status tab, and its Setup tab's **Updates** line says whether updates are pinned, held or following the newest build. ## Badge sign-in presets The settings window's **Setup** tab sets a machine up for one of two sign-in methods. Choose it under **Sign-in method**; the lines below it then check what that method needs (choosing saves nothing). **Apply the ... sign-in preset** saves the preset as the machine's own settings, merged into what is saved there already, and asks first. | | Smartcard (PIV certificate) | Entra FIDO | |---|---|---| | The badge signs in with | the certificate in its PIV applet (a Kerberos smart card logon) | its passkey for Microsoft Entra ID | | The machine must be | in an Active Directory domain | Microsoft Entra joined, or hybrid joined with Microsoft Entra Kerberos set up in Active Directory (Microsoft's "Enable passkey sign-in to on-premises resources") | | Windows | 10 or 11 | 10 1909 or later, 11 (hybrid joined: 10 2004 or later); not Windows Server | | Each user needs | a certificate on the badge, strongly mapped to the user in AD | a passkey on the badge registered to the user's Entra account, with the Passkey (FIDO2) method allowed for them | | Bridge interface | smart card reader on, FIDO off | FIDO on, smart card reader off | Both presets set the same keys, so applying one after the other leaves nothing of the first: - `credential_provider`: `credprov_enabled` on; `credprov_logon_method` `smartcard` or `aad_fido`, and the superseded `credprov_aad_fido_logon` to match it (CDM refuses the two when they disagree); `credprov_auto_start`, `credprov_auto_connect_on_select` and `credprov_auto_fido_on_roster_connect` on (the sign-in starts once the badge connects); `credprov_name_from_credential` on; `credprov_fido_nudge` off; `credprov_rssi_min` -60 and `credprov_hysteresis_db` 10 (a tile above -60 dBm, kept down to -70). - `bridge_settings`: `smartcard_bridge_enabled` and `fido_bridge_enabled` for the method; `rssi_connect_threshold` and `rssi_fastconnect_threshold` -40 (connect only a badge held close); `rssi_disconnect_threshold` 0 (keep it until the link is lost). Switching the bridge's interface re-enumerates it on USB; the new interface appears within about ten seconds. On a machine where no method is set yet, the Setup tab starts on Entra FIDO if the machine is Entra joined and not in a domain, and on smartcard otherwise. For Entra FIDO the Setup tab also checks the Entra join, the Windows version and the bridge's FIDO interface, and reports whether Windows' own security-key sign-in policy is on. The preset does not change that policy. A preset is saved as this machine's own settings, so Group Policy and "Apply until restart" still win over it. When they state part of a preset otherwise (a GPO that pins the bridge's mode, for example), the Setup tab says what the machine would end up running and that the preset cannot change it; change the GPO instead. ## Updates in production: pin the versions With no update policy, the agent installs the newest build of its STABLE channel by itself, and the bridge firmware stays where it is. In production, nothing should follow the newest build on its own. Pin both, and raise the pin once a new version has been tried on a few machines: ```json {"agent_update_policy": {"mode": "pinned", "target_version": "1.0.NNN", "channel_url": "https://release.crayonic.io/Agent/STABLE/"}, "fw_policy": {"mode": "pinned", "target_version": "1.4.NN", "channel_url": "https://release.crayonic.io/Firmware/STABLE/"}} ``` - A pinned version must be published on the channel in `channel_url`, or nothing is installed. - A policy never downgrades the agent or the bridge. - `{"mode": "hold"}` stops updates altogether. **Pilot:** link a second GPO to the pilot OU. Give it the **complete** document with only the versions raised: start from the document you exported for the main GPO and change only `target_version`. - Both GPOs write the same single value. The GPO applied last (the one linked closer to the computer, unless the other is Enforced) replaces the other's document entirely. Nothing merges between GPOs. - A pilot document that holds only the update policies therefore drops every other section the main GPO states. On the pilot machines, CDM's values or the machine's own values take over for those sections. ## Removing the old credential provider (CP1/CP2) Machines that still have the old Crayonic credential provider should lose it before the agent's provider (CP3) takes over the logon screen. The agent removes it itself. - **One machine:** open the settings window and click **Setup > Remove the old provider**. - **Many machines:** use a computer **startup script** (Computer Configuration > Policies > Windows Settings > Scripts > Startup) such as: ```batch @echo off set "EXE=%ProgramW6432%\CrayonicAgent\CrayonicAgentService.exe" if not exist "%EXE%" exit /b 0 "%EXE%" --settings --remove-old-provider >> "%ProgramData%\CrayonicAgent\remove-old-provider.log" 2>&1 exit /b %ERRORLEVEL% ``` The command waits up to 5 minutes for the agent to start; `--wait SECONDS` changes that. It exits with: - `0`: removed, or nothing to remove; - `3010`: removed, and a restart finishes the job; - `1`: failed, and the log says why. For a PowerShell startup script or an Intune script, use the PowerShell form under "Running the command line from scripts". Otherwise the exit code is lost. ## Repair and upgrade behavior - The local registry component is authored with `NeverOverwrite="yes"` and `Permanent="yes"`. Repairs, upgrades and uninstalls therefore keep values an administrator set, including the machine's settings document. - The Policies key always wins over the local values. ## Troubleshooting - **GPO install:** the MSI and MST paths must be UNC paths that computer accounts can read. Do not move or rename the files while the GPO deploys them. Check that the MST is listed on the package's **Modifications** tab. - **Installer results:** see Windows Event Log > Application (MsiInstaller). For manual installs, collect a log with `/l*v C:\Temp\crayonic_install.log`. - **Cloud Sync still on despite the MST:** the MST applies only to a first install. Check that no Policies value forces it on, or set `CloudSyncEnabled = 0` in the Policies key. - **Settings document refused:** `--settings --terminal-only` prints the reason, with the line and column of the JSON error. A document pasted over several lines is the usual cause. Fix it at once (see "A refused document is urgent"). - **Something in the document has no effect:** look for its `!` line in `--settings --terminal-only`, or in the banner and the Status tab of the window: a misspelt key or a value out of range is named there. ## Security considerations - Standard users can read HKLM; writing requires an administrator or Group Policy. - Prefer the Policies key for compliance, and manage it with Group Policy or MDM. ## FAQ - **Does turning Cloud Sync off affect the bridge, badges or agent updates?** On a machine CDM never configured, no: they keep working, and updates still download from release.crayonic.io. On a machine CDM configured, CDM's settings are dropped: agent updates follow the newest STABLE build unless a document states a policy, bridge firmware is held, badge sign-in set up by CDM stops at the next restart, and badge firmware updates stop. Export the settings first. See "Cloud Sync". - **Can the setting be enforced centrally?** Yes: set `CloudSyncEnabled` under `HKLM\SOFTWARE\Policies\Crayonic\Agent` with Group Policy (Preferences or a registry policy) or MDM. - **What if we upgrade later without the MST?** Existing values stay as they are. A Policies value, if set, always wins.