Skip to content

Crayonic Agent

Overview

The Crayonic Agent is a Windows service that runs on each managed endpoint. It watches Crayonic devices (Badge, KeyVault, Bridge), user sessions, smart-card readers and certificates, reports them to Crayonic Device Manager (CDM), applies CDM policies and firmware updates to the devices attached to the machine, feeds the Crayonic Credential Provider with the list of nearby badges, and hosts the local helper that Crayonic Credential Manager (CCM) uses to write credentials to a wallet from the browser.

Where this fits

The Agent is the only Crayonic software on the endpoint that talks to the servers: it reports to CDM (REST and MQTT), receives firmware and policies from it, and serves CCM locally on https://localhost:17620; see Solution Architecture, Options 2 and 3.

flowchart LR
  subgraph EP["Managed Windows endpoint"]
    BADGE["Badge / KeyVault<br/>(USB or via Bridge)"]
    BRIDGE["Crayonic Bridge"]
    AGENT["Crayonic Agent<br/>Windows service"]
    CP["Credential Provider<br/>(logon screen)"]
    BROWSER["Browser: CCM"]
    BADGE --- BRIDGE --- AGENT
    BADGE --- AGENT
    AGENT -. "named pipe: badge roster; registry: settings" .-> CP
    AGENT -. "https://localhost:17620" .-> BROWSER
  end
  CDM["CDM"]
  CCM["CCM backend"]
  AGENT -->|"REST: enrollment, events, settings<br/>MQTT: status, events, advertisements"| CDM
  CDM -->|"policies, firmware, commands"| AGENT
  BROWSER --> CCM

What the Agent does on the endpoint

  • Session events — logon, logoff, lock, unlock, console and RDP connect/disconnect, with user identity and session context.
  • Reader and device events — smart-card reader availability; Crayonic KeyVault and Badge connection and removal with firmware version and battery level; certificate discovery with issuer and expiry.
  • Bridge events — Bridge attached/removed, firmware version, current settings, and which wallets are connected through it; summaries of the BLE advertisements the Bridge hears (which badges are near this machine).
  • Sign-in telemetry — with the Credential Provider installed, each badge sign-in ceremony is reported (started/finished, whether it was triggered by a tile click or by proximity, duration and result) and reconciled with the Windows session event in CDM.
  • Firmware updates — Bridge firmware is updated over USB according to the CDM firmware policy for the organisation, group or pilot cohort. Badge firmware is pushed on command from CDM to the machine the badge is currently attached to, with a choice of applying immediately, in a quiet moment, or after the user confirms on the badge.
  • Bridge settings — the effective Bridge settings computed in CDM (FIDO/smart-card bridging, RSSI connect / disconnect / fast-connect thresholds) are written to the attached Bridges automatically.
  • Workstation lock — locks the workstation when the user's badge disconnects (enabled by default, configurable).
  • Credential Provider — installs the Crayonic Credential Provider and keeps it updated, serves the logon screen a roster of nearby badges with their names over a local named pipe, and writes the provider's settings. If the Agent is not running, the provider shows at most a tile saying the service is starting, and never blocks the standard Windows tiles.
  • CCM local helper — see Integration with Crayonic Credential Manager.
  • Legacy application autofill — optional integration with the Crayonic Password Manager for legacy Windows applications.
  • Offline buffering — events are stored locally while the network is unavailable and delivered on reconnect.
  • Remote diagnostics — CDM administrators can request a diagnostics dump, refresh settings, rescan Bridges, change the log level, force a firmware/update check or restart the service from the CDM console.

Security posture

  • Enrollment with proof of possession. On first start the Agent generates a machine identity key (sealed with Windows DPAPI) and "knocks" at CDM with its machine information and authentication proofs (self-signed identity; Entra-joined device and Active Directory machine certificate where available). An administrator approves the pending machine in the CDM console and assigns it to an organisation, or, where the organisation has configured trusted enterprise root CAs, a machine whose certificate chains to such a root is enrolled automatically. In both cases the Agent must sign a fresh server challenge with the private key, so a copied certificate is not enough. The --show-enrollment command on the endpoint shows the approval code and status.
  • Machine-bound, short-lived tokens. Once enrolled, every API token is obtained by signing a fresh challenge with the pinned machine key; tokens are short-lived and scoped to the machine's organisation. CDM can revoke a machine or reset its pinned key at any time.
  • Encrypted transport. All traffic to CDM is HTTPS/TLS, and the MQTT connection uses TLS with certificate verification against the Windows trust store (an internal CA can be added to the store or delivered by CDM). No unauthenticated event submission.
  • Signed installer, verified updates. The Agent ships as a signed MSI. The self-updater downloads new releases from the configured channel, verifies their signature against a key built into the Agent before installing, and limits install attempts so a broken package cannot loop.
  • No inbound network surface. The service exposes no listening port other than the CCM helper on 127.0.0.1:17620, which is bound to localhost only and refuses remote access. Local IPC uses named pipes with restrictive ACLs; the service's data directory is readable by SYSTEM and Administrators only.
  • Least trust in settings. Cloud-delivered settings are validated before they are applied, and the update signing key cannot be overridden by settings.

System requirements

  • Windows 10 or Windows 11 (x64)
  • Administrator privileges for installation
  • Outbound HTTPS to the CDM backend (port 443) and MQTT over TLS (port 8883) to the CDM broker
  • Local port 17620 free for the browser-based CCM integration (never exposed outside the machine)

Installation

The Agent ships as a signed MSI (CrayonicAgent_x64_<version>.msi) suitable for Group Policy, SCCM/MECM and Intune, or for local installation.

  1. Download the latest Crayonic Agent build from the Downloads page.

  2. Install silently with the CDM backend URL supplied by your CDM administrator:

    msiexec /i "CrayonicAgent_x64_<version>.msi" CLOUDSYNCURL=https://cdm.example.com /qn

    CLOUDSYNCENABLED=0 installs the Agent with Cloud Sync off: it then sends nothing to CDM (Bridge, badge and update functions keep working); a ready-made transform (.mst) for that case is shipped with each build.

  3. With Cloud Sync on, the Agent enrolls the machine with CDM on first start (see Security posture). Approve it in the CDM console under pending enrollments, or rely on trusted-CA auto-enrollment.

  4. Confirm the Crayonic Agent service is running under services.msc.

Group Policy: publish the MSI from a UNC share (Computer Configuration → Software installation, Assigned), adding the .mst under Modifications if needed. SCCM / Intune: wrap the same msiexec command line and detect by MSI product code.

Configuration

Settings are read from the registry, with the policy hive taking precedence:

Key Values
HKLM\SOFTWARE\Policies\Crayonic\Agent (GPO / MDM) CloudSyncEnabled (DWORD), CloudSyncUrl (REG_SZ), LogLevel (REG_SZ)
HKLM\SOFTWARE\Crayonic\Agent (set by the MSI) same values, local fallback; preserved across repairs and upgrades

Everything else — Bridge settings, firmware policy, Credential Provider settings, lock behaviour — comes from CDM, or without CDM from the Agent's settings window or a Group Policy document (see Badge Sign-in Setup); a refresh_settings command from the console applies CDM changes immediately.

Integration with Crayonic Credential Manager

When CCM runs in the browser it needs to reach the user's wallet, which a web page cannot do on its own. The Agent therefore hosts CCM's local helper on https://localhost:17620: a small HTTPS service bound to localhost only, restricted to the CCM web origins configured for your deployment, that performs the FIDO2 ceremonies and device operations against the USB-attached (or Bridge-attached) wallet. The helper supports validation of per-operation tokens issued by the CCM backend (fetched from its JWKS endpoint) and origin-bound consent sessions, so passkeys and certificates can be written to the user's hardware wallet from a normal web session without browser plug-ins.

Logs and troubleshooting

  • The service writes to its log directory under %ProgramData%\CrayonicAgent and to the Windows Event Log; the CDM console can request a full diagnostics dump remotely.
  • Machine not appearing in CDM — check that the enrollment was approved (pending enrollments in the console, or CrayonicAgentService.exe --show-enrollment on the endpoint), the outbound HTTPS/MQTT routes, and the configured backend URL. For an internal-CA broker certificate, make sure the CA is in the Windows trust store.
  • Browser shows "Agent disconnected" in CCM — confirm the service is running and that https://localhost:17620/v1/info answers in a local browser; a blocked local port or an untrusted certificate is the usual cause.
  • Bridge settings or firmware not applied — use Rescan bridges / Check firmware from the console; the Bridge must be attached by USB and no other tool may hold its management interface.
  • Badge firmware update fails — confirm the badge is connected and that the user has confirmed any on-device prompt.

Download

Latest Agent builds are on the Downloads page.