Skip to content
English
  • There are no suggestions because the search field is empty.

How to run a successful pilot group

Summary

A pilot puts monitoring on a small, deliberately chosen group before you commit the whole organization. This runbook covers choosing that group, deciding between a manual and a managed rollout, pacing the enrollments so they do not fail, confirming the group is reporting, and diagnosing a device that will not connect.

A pilot of 10 to 20 people is the size this is written for. That is large enough to surface the problems a single test machine never will (mixed operating systems, locked-down browsers, people who close the installer halfway), and small enough that you can chase every device personally.

For a single first device, use Add your first device instead. This article assumes you have already done that once and are now scaling it.

Before you start

Confirm the platforms in your pilot group are supported. Minimum system requirements is the authoritative list. The two constraints that most often exclude someone from a pilot group: the browser extension runs only in Chromium browsers (Chrome and Edge are supported; Brave and Arc run it but aren't certified), so Firefox and Safari users cannot take part in the extension half, and the endpoint sensor has no Windows on Arm or Linux on Arm build, so those machines cannot take part in the sensor half.

Confirm your own access. Enrolling devices needs the Manage Users or Manage Tenant permission, and reading fleet health in the Fleet view needs Manage Users. Without it the pages are visible but the controls are inert.

Know which of the two channels you are piloting. They are independent and can be run separately:

Channel Covers Availability
Browser Extension AI activity in Chrome and Edge (Brave and Arc run it but aren't certified) Every Plan
Endpoint Sensor Desktop AI applications, command-line and IDE tools, other browsers, local models Every Plan

Piloting both at once on the same machines is fine and is the realistic configuration, but if something goes wrong you will not know which channel caused it. If this is your first pilot, stage them: extension first across the whole group, then the sensor.

1. Choose the pilot group

Aim for 10 to 20 people, chosen for coverage rather than convenience:

  • At least two of every operating system you will eventually deploy to. One machine per OS tells you the installer runs. Two tells you it runs twice.
  • At least one person who is not technical. A pilot staffed entirely by engineers will not surface the enrollment questions your actual rollout generates.
  • At least one heavy AI user and one light one. The heavy user shows you what normal volume looks like; the light user shows you what a quiet sensor looks like, so you can tell quiet from broken later.
  • Nobody on leave during the pilot window. A device that never comes online is indistinguishable from a device that failed to enroll.
  • Avoid executives for the first pilot. The first pilot is where the install problems are.

Record the list before you start, with each person's operating system and browser. You will need it to tell "18 of 20 reporting" from "18 reporting and I am not sure who the other two are".

Check your device capacity before you begin. Your license gives each user seat a device allowance. Unless your agreement sets a different number, it is 2 devices per user on Starter, 3 on Professional and 4 on Ultimate, and some licenses don't meter devices at all. A pilot of 20 people on laptops and desktops can consume more of the pool than expected. Your current usage and allowance are shown under Device metering in Configure → Organization → Plan & features.

2. Decide: manual install or managed install

This is the decision that shapes everything else about how the pilot runs. See Manual install versus managed install below for the full comparison, including one capability that a manual install cannot give you at any plan level.

In short: a managed install is pushed centrally through your device management system and needs nothing from the person. A manual install is run by the person on their own machine from instructions you send them. Most pilots use manual installs because the device-management work is not ready yet, and that is a reasonable way to start, as long as you know what it changes.

3. Pace the enrollments

This is the step most pilots get wrong, and the failure looks like a broken product.

Enrollment is rate limited by network address: ten enrollments in any fifteen minute window, counting both the successful ones and the failed ones. Everyone in one office shares one outbound address.

So a pilot of 10 to 20 people who all enroll in the same session will succeed for roughly the first ten and then start being refused, with a message asking them to try again later. Nothing is wrong with those devices, their tokens, or your configuration. They were simply eleventh.

Pace it instead:

  • Enroll in batches of no more than eight, leaving at least fifteen minutes between batches. Eight rather than ten leaves headroom for a retry or two.
  • Or split by location. People working from home each have their own address and do not compete with one another, so a remote pilot group can enroll at will. It is a single office that concentrates the problem.
  • Or stagger over days. Four people a day for a working week is entirely reasonable for a pilot and removes the problem completely.

If a device is refused, stop and wait rather than retrying immediately. A device that retries in a tight loop keeps the window full and blocks everyone else at that location.

4. Deploy the browser extension

Manual. From Configure → Capture & devices → Browser extension, generate the enrollment secret and copy the compound code it derives. Send each person the Add to Chrome link from that page and the compound code. They install the extension from the Chrome Web Store, open it, and paste the code once. In Microsoft Edge, a manual install first needs Allow extensions from other stores switched on in Edge's extensions page.

Distribute the compound code, not the secret. The compound code carries both your address and the secret. A browser given only the secret has nowhere to report to, so it will install and then sit idle, which reads in Fleet as a device that never enrolled.

If you use the self-hosted package (under Advanced on the Browser extension page, for organizations that cannot depend on the Chrome Web Store), the person must grant it explicit site access. Without that the browser reports the extension as having no additional access and it captures nothing, while still appearing installed.

Managed. Force-install the extension by its Chrome Web Store ID through your device management system. To spare people the paste step, also set two zero-touch policy values:

Policy Key Value
backendURL Your CyberHQ.ai address
enrollmentCode The enrollment secret from Configure → Capture & devices → Browser extension

With both set, the extension configures itself and the person never sees a setup page.

Ready-to-import policy files and deployment guides are on the Browser extension page itself, covering Google Admin Console, Microsoft Edge management, Windows Group Policy, macOS device management and Microsoft Intune. If your fleet already force-installs the self-hosted package, use the migration guide on the same page to remove it as part of the move; otherwise both extensions install side by side and each person's activity is recorded twice.

One timing behavior worth planning around. Managed policy does not always arrive at the same moment the extension does. A browser can receive the extension immediately and the policy values some time later, occasionally much later. During that gap the extension is installed but not enrolled, and the person shows as missing from your fleet. Before chasing it as a failure, confirm the policy has actually reached the machine.

5. Deploy the endpoint sensor

Check the allowed email domains first. Self-enrollment requires the enrolling person's email domain to be permitted under Configure → People & access → Sign-in & domains, and that list applies regardless of your registration mode. A missing domain there is one of the most common enrollment rejections, and in a pilot it will reject everyone at once rather than one person, so it is worth confirming before you send anything out.

Generate an enrollment token from Configure → Capture & devices → Install on devices. Tokens are valid for between 1 and 90 days. By default a token is bound to the issuing administrator's email; a separate fleet token option skips that binding for mass deployment and requires explicit confirmation, because any machine holding one can register under whatever email it is given.

A token is shown once. Admin-issued tokens display their value with a copy button, and a token bound to one person also has a download button that saves a token file for the Windows Setup.exe; self-enrollment tokens are shown at generation and never again. If one is lost, issue a new one rather than looking for the old value.

Never put a token on a command line you will screenshot, paste into a ticket, or leave in shell history. A token is a credential: anyone holding it can enroll a machine into your organization. The installers on every platform accept the token from a file or a prompt for exactly this reason. If a token is exposed, cancel it from the same page and issue a replacement. Canceling blocks future use only, so devices already enrolled with it keep working.

Platform Customer Install Path Service or Daemon Log
Windows Setup.exe for a person's own install (with a downloaded token file for a token bound to that person), or .msi with the token as an install property for IT or device-management deployment CyberHQAISensorDaemon C:\ProgramData\CyberHQ.AI\sensor.log
macOS .pkg, or the guided self-install wizard com.cyberhq.ai.sensor /var/log/cyberhq-sensor.log
Linux install script, systemd unit cyberhq-sensor.service

/var/log/cyberhq-sensor.log

On macOS the guided wizard is the better choice for a manual pilot: it walks the person through the privileged install step and confirms enrollment on screen, so they can tell you it worked without you checking.

6. Confirm the pilot is reporting

Open Coverage → Fleet. Each pilot device should appear and move to healthy after its first check-in.

Check against the list you recorded in step 1, not against a count. "18 of 20" only helps if you know which two are missing.

Give it time before calling anything failed. How long a quiet sensor takes to be flagged is configurable under Configure → Detection → Monitoring thresholds, and the default is generous enough that a machine which was asleep during your check can look stale without being broken.

Diagnose a sensor that is not connecting

Three checks, in order. They need nothing beyond what is already on the machine.

1. Is the sensor running?

Platform Where to look
Windows Services, for CyberHQAISensorDaemon
macOS Activity Monitor, for the CyberHQ.ai sensor process
Linux systemctl status cyberhq-sensor.service

Not present at all means the installer did not complete. Present but stopped means it installed and failed to start. Those are different problems, and saying which one you have saves a round trip.

2. Is the log being written?

The log paths are in the table under Deploy the endpoint sensor. If the file is not there, the sensor has never started. If it is there but has not been written to for half an hour on a machine that is awake, the sensor is not working properly whatever the service state says.

3. What does the last enrollment line say?

Search the log for enrol. Each attempt and each refusal is recorded. A refusal reads like this:

enrolment refused (HTTP 403): {"error":"Invalid enrolment token"}

The number and the message after it are the whole diagnosis. The wording before the number is the same for every refusal, so on its own it tells you nothing.

Response What it means Who resolves it
400 The request was malformed, or the email does not match the one the token is bound to. The message names the field.  
403

Refused: an expired or canceled token, a capacity limit, a license that withholds the sensor, or a device with more than one user.

 
429 Too many enrollments from this location. See Pace the enrollments.  
500 A server-side error. Nothing on the device or in your settings will change it.  

A 500 tells you more than it appears to. Every other cause returns a named message, so a bare "Internal server error" positively rules out the token, the user, your seat capacity, your plan and your configuration. Do not spend time reissuing tokens or checking seats. Go to support.

If you see 429 and 500 alternating, that is one fault, not two. A device retrying quickly enough exhausts the enrollment window by itself, so the throttle appears on top of whatever the real error is. Stop the sensor, wait fifteen minutes, start it once, and read the first response. That one is the real error.

Common faults during a pilot

What you see

What it could be

The first several devices enroll, the rest are refused

The enrollment rate limit. See Pace the enrollments. Not a fault.
A device is refused immediately, message names the token The token expired or was canceled. Issue a new one.
A device is refused, message mentions a limit

You have reached your user-seat or per-user device allowance. Free a device by archiving one from Fleet, or add capacity.

Extension installed but the person never appears

On a managed rollout, the policy values have not reached the browser yet. Confirm the policy landed before treating it as a failure.

Sensor installed, service running, nothing in Fleet

Read the last enrollment line in the log, per Diagnose a sensor that is not connecting. A device that is running but sending nothing is a different problem from one that never installed.

Everything enrolls, one person shows no activity

Not necessarily a fault. A light AI user generates little. Compare against the heavy user you deliberately included

A device drops to stale overnight, recovers in the morning

The machine was asleep. Check the threshold under Configure → Detection → Monitoring thresholds before investigating.

The same refusal repeats every few seconds

Stop the service on that device. A retry loop keeps the rate-limit window full and blocks everyone else at that location.

For a single device that will not report, the fuller walkthrough is an endpoint sensor isn't reporting.

Manual install versus managed install

Both produce a working sensor and a working extension. They differ in three ways that matter for how you run the pilot.

One capability is managed-only, in the browser. A hard block in the browser, where the request is actively prevented rather than recorded, requires the extension to be deployed under managed policy. This is on top of your plan: blocking needs Professional or Ultimate, and even then a browser the person installed themselves can't hard block. Warning and soft-block behavior do work on a self-installed extension.

This applies to the browser channel specifically. Blocking on devices depends on your plan (Professional or Ultimate) rather than on how the sensor was installed. On Starter, a pilot can validate visibility, detection and alerting, but not blocking.

The consequence for pilot design: if the point of your pilot is to evaluate browser blocking, it has to be a managed pilot. A manual pilot can validate visibility, detection, alerting, and warn and soft-block behavior, but it will tell you nothing reliable about hard blocking.

Enrollment timing behaves differently.

  Manual Managed
Who acts

Each person, when they get to it

Your device management system, on its own schedule
Timing

Each person, when they get to it

Can fire simultaneously across the group, which hits it

Pacing control Tell people when to install Stage the deployment ring by ring
Failure visibility The person tells you it failed Nobody tells you; you find it in Fleet

A managed rollout is the one more likely to hit the enrollment rate limit, because a policy push does not naturally stagger. Deploy to a ring of eight, confirm, then the next ring.

What the pilot actually proves differs.

A manual pilot tests the instructions as much as the product. If people struggle, that is a finding: it is what your wider rollout will look like. It does not test your device-management configuration at all, so a successful manual pilot tells you nothing about whether the managed rollout will work.

A managed pilot tests the deployment mechanism, which is the part that has to work at scale, but it hides the end-user experience because there is nothing for the person to do. It also introduces the policy-arrival delay described in step 4, which manual installs do not have.

A reasonable pattern if you intend to end up managed: run a small manual pilot first to validate the product and gather feedback, then a second, managed pilot ring to validate the deployment mechanism before the wider rollout. The two pilots answer different questions and the second is much faster than the first.

When to escalate

Contact support when the log shows a server-side error, or when a device is refused with a message you cannot map to anything above. Include:

  • The last enrollment line from the log, copied exactly, including the response code and message
  • The operating system and whether the install was manual or managed
  • Roughly when the device first tried, and whether others at the same location succeeded

Do not include the enrollment token.

Related