Installing the Windows agent

The agent is what turns a PC into a managed computer. Without it there is no monitoring, no patching, no remote control and no inventory.

This guide covers the whole path: building the installer, getting it onto the machine, confirming it enrolled and, above all, knowing what to look at when the computer does not show up.

Building the installer

Go to Customers, open the customer, Computers tab, Installer section, + Create Installer button. You need computer management permission.

A dialog opens with two tabs, Windows and Linux. On the Windows tab you fill in:

Then Generate. The build takes between 30 and 90 seconds, and the screen tells you so.

Do not close the dialog while it is building. Closing it mid-build discards the installer and you have to start over. Once it says Installer ready, you can close it safely: it stays in the customer's installer list.

The three optional labels travel inside the MSI and fill themselves in on the computer record when it enrolls. If you build the installer without them, those fields stay empty.

What that file is

An MSI of roughly 17 MB, named kairoslink-installer-{number}.msi.

The installer is per customer, not per organization. It carries that customer's enrollment credential inside, which is why one customer's MSI does not work for another.

One MSI works on several computers of the same customer for 7 days. You do not need one per machine: build one and use it for the whole batch.

What the installer does not carry is the remote desktop password. The machine itself generates it, applies it hashed and reports it to the panel on enrollment. It is never stored in plain text in the installer or on disk.

Getting it onto the machine

There are four paths, and you pick by scale.

Direct download

From the dialog you just generated, or from the row menu in the installer list, Download. You need to be signed in.

Public link, no sign-in

Copy link button. It produces an address anyone can open with no username and no password: send it to the person at the machine and they download the MSI themselves.

It is the fastest path for installing on a machine that is far away. The link expires after 7 days, same as the installer, and the screen shows you the exact date.

That link is a credential: whoever holds it can add computers to that customer while it is valid.

Silent installation

With the MSI on the machine, in an elevated console:

msiexec /i "C:\path\kairoslink-installer-123.msi" /qn /norestart /L*v "C:\ProgramData\KairosLink\deploy\msi.log"

/qn installs with no interface, /norestart avoids the reboot and /L*v leaves a detailed log that is useful for diagnosis later.

There are no command-line properties to pass. There is no TOKEN= and no SERVER=: the credential already travels inside the MSI, so the command is always the same.

This is the command to use if you deploy with your own script or another tool.

Mass deployment via GPO

If the customer has a domain and you already have the agent installed on the Domain Controller, KairosLink builds the GPO for you.

Under Monitoring, Active Directory, deploy option: Install agent on domain computers. This needs the agent deployment permission, which by default only Owner and Admin have.

The Domain Controller copies the MSI to SYSVOL and creates a policy with an immediate task that runs on each selected computer as SYSTEM. You choose between Automatic delivery, which creates and links the GPO, or Manual, which leaves you a backup to import with GPMC.

Two things determine the outcome:

• When it installs. The path that installs for sure is the reboot. If the immediate task also runs, it installs earlier, on the next policy refresh, roughly 90 minutes to 2 hours.
• With Manual delivery the GPO is not linked. Until you link it yourself with GPMC, no computer installs anything no matter how created the campaign looks.

The cap is 500 computers per campaign. If a computer already has KairosLink installed, the script does not reinstall it.

What the machine needs

Local administrator privileges. The MSI installs a service, so the console has to be elevated. Under GPO deployment this is already handled, because it runs as SYSTEM.

Outbound internet on 443. The agent needs to reach the panel over HTTPS to enroll, send heartbeats and receive commands, plus relay.kairoslink.io over WSS for remote control when there is no direct path.

No public IP and no inbound ports required. All connections are initiated by the agent, outbound. Remote control negotiates the path in three steps: LAN, direct peer connection, and relay as a last resort when NAT or the firewall block the direct route.

The machine does not need to reach GitHub. The panel proxies the binary, so the download always comes from a KairosLink domain.

TLS 1.2. Older Windows versions that do not support it may fail to report.

Before registering a new computer, KairosLink checks your plan's cap. A reinstall over a computer that already exists never hits that cap.

What happens on first start

As soon as the agent starts, it enrolls against the panel: it presents the credential carried in the MSI, reports its hostname and hardware fingerprint, and generates the remote desktop password it reports to the panel.

If everything checks out, the panel responds and issues that machine its own individual credential.

The computer appears instantly. There is no queue and no intermediate process: as soon as enrollment responds, the computer is already listed under Devices as online.

From then on it sends a heartbeat every 20 seconds. If it stops, it flips to offline after 70 seconds.

What fills itself in

From the agent: hostname, operating system, version, CPU, memory, public IP, local IP and the remote desktop identifier.

From the installer: site, department and device type, if you set them when building it.

Email alerts for that computer start switched off, on purpose. The computer is monitored from minute zero, but it will not send a single email until you flip the switch on its record. If you install an agent and expect an email about something, it will not come until you enable it.

Computer notes are left empty: those are filled in by hand.

Confirming it worked

In the panel, the Devices screen. Find the computer and look at the Last seen column: that is what confirms it is actually alive and not just registered. A computer that enrolled but is not sending heartbeats flips to Offline after 70 seconds.

The panel distinguishes Offline from Offline without notice. The first is a shutdown the agent announced; the second is a power cut, a hang or a network loss. An agent that never spoke falls into the second category.

On the machine, the product is registered in Windows uninstall with a name starting with KairosLink. If you installed with /L*v, the msiexec log tells you exactly what happened.

When the computer does not show up

This is the part that matters. Every cause has a symptom that tells it apart from the others, so the diagnosis order is this:

Step 1: did the installation finish cleanly?

Check the msiexec exit code, or the log if you used /L*v. The most common codes:

If the code is 0 and the computer still does not appear, installation is not the problem: the problem is network or credential. Move to step 2.

Step 2: the computer does not appear at all

These are the real causes, in order of frequency:

The MSI expired or its credential was rotated. An installer lives 7 days. And if someone rotated that customer's enrollment credential, every MSI built before that becomes useless for new registrations. Fix: build a new installer.

The installer's customer was deleted. Deleting a customer revokes their enrollment credentials. The agent gets an explicit message saying that installer belongs to a customer that no longer exists.

The plan's computer cap was reached. This only affects new computers. If you are reinstalling over one that already exists, this is not it.

The machine has no route to the panel. This is the only silent case: nothing is recorded on the server side, because the connection never arrived. If the computer is nowhere to be found and the installation returned 0, try reaching the panel on 443 from that machine.

Step 3: the computer appears but does not report

The system was reinstalled, an image was restored, or the motherboard was replaced. The computer already had its individual credential and now presents a different hardware fingerprint, so KairosLink rejects the re-enrollment on security grounds. This is the only case where the computer is in the panel, with a complete record, and enrollment fails anyway.

Fix: on the computer record, Revoke credential. The agent then re-enrolls on its own.

The computer was moved between customers and its agent is an older one. If the agent has no individual credential, it depends on the customer's shared credential. Once moved, that credential no longer matches and the computer stops reporting. Fix: reinstall with the new customer's installer.

The computer's credential was revoked from the panel. The agent cuts off immediately and does not come back until it re-enrolls.

Step 4: it installs, appears briefly and disappears

Someone pressed Uninstall agent on that computer and the flag is still set. Reinstalling does not clear it: the agent enrolls, receives the uninstall order on its first heartbeat and leaves.

It is easy to spot because the computer shows up in the list and vanishes on its own within seconds.

If you deployed via GPO and nobody enrolls

The panel has its own diagnosis on the campaign, which checks up to 25 computers per run and tells you which of these happened:

• The computer never processed the policy, because it did not reach it or it has not refreshed since it was created
• The computer reports the GPO as denied
• The policy does not appear in that computer's list
• Nothing could be checked because the computer does not answer port 135 from the DC
• The Task Scheduler log is disabled on that computer
• The task ran and msiexec failed, with the code and its translation
• The installation ran fine and the agent has not made contact, which is the case where the problem is network or credential, not deployment

It is worth keeping in mind what the panel itself warns you about: the GPO being created and linked correctly only tells you what the Domain Controller did. What happens on the computers is unknown until you request the diagnosis.

Uninstalling

There are three distinct actions and they do different things:

Uninstall agent is the recommended route: it leaves both the machine and the list clean.

Remove from list is for when the machine no longer exists. If the agent is still installed somewhere, you will have to uninstall it there.

If you delete the whole customer, their computers stop appearing and their open alerts are closed, but the agent stays installed on every machine. To leave them clean you have to uninstall it on each one.

Reinstalling

Reinstalling over an existing computer does not duplicate it: KairosLink recognizes it by its hardware fingerprint and, failing that, by hostname.

Two things a reinstall does overwrite, worth knowing:

• The computer name. If you renamed it by hand in the panel, it reverts to the installer's name or to the hostname.
• Site, department and device type. They are rewritten with whatever the new MSI carries. If you built that MSI without labels, those fields end up empty.

What is not overwritten is the email alert switch: reinstalling the agent does not turn emails back on for a computer that had them off.

Moving a computer between customers

The correct path is to edit the computer and change its customer from its record. Do not reinstall.

If that computer has an individual credential, it keeps reporting without you touching anything.

If it is an older agent using the customer's shared credential, it stops reporting after the change and has to be reinstalled with the new customer's installer.

Updating the agent

The agent does not update itself. You dispatch the update from the panel: customer record, Agents tab, Update agents button.

Only computers that are online and not already on the current version are eligible. The dispatch goes out in batches of 10 computers every 5 minutes, so the whole fleet is not hit at once.

The agent verifies the file's integrity before running it, and will not run it if it does not match. Since the agent reinstalls itself, confirmation that it worked is the next heartbeat reporting the new version. If nothing arrives within 15 minutes, it is marked as failed: a computer never gets stuck on "Updating" forever.

An older agent keeps working. On the Agents screen it is grouped under unknown while it does not report its version in the heartbeat.

What it does not do today

• There is no Intune, SCCM, PDQ or Chocolatey integration. Mass deployment is via GPO from the panel, or with your own script using the public link and the msiexec line.
• There is no per-organization agent version. The current version is a single one across the platform. You choose when to update and which computers, not which version.
• The agent never updates itself. The panel always dispatches it.

Frequently asked questions

Do I need one installer per computer? No. One per customer works for every computer of that customer for 7 days.

Does one customer's MSI work for another customer? No. It carries that customer's credential inside.

How long until the computer appears? Instantly. As soon as the agent enrolls, it is in the list.

I installed and nothing shows up. Where do I start? With the msiexec exit code. If it returned 0, installation is not the problem: check whether the machine can reach the panel on 443, and whether the installer expired.

I restored an image and the computer stopped reporting. Its hardware fingerprint changed. Go to the computer record and use Revoke credential: the agent re-enrolls on its own.

Can I install it without being an administrator? No. The MSI installs a service and needs elevation.

Do I need to open ports on the customer's firewall? Not inbound. The agent initiates every connection outbound on 443.

I uninstalled the agent by hand and the computer is still in the list. That is expected. Use Remove from list to take it out of the panel.

I moved a computer to another customer and it stopped reporting. Its agent uses the previous customer's shared credential. Reinstall it with the new customer's installer.

I installed the agent and no alert emails are arriving. Email alerts start switched off on every computer. Flip the switch on the computer record.