When building device images that include the Kolide Agent, it is important to understand how the node authenticates with Kolide's servers, and what part of the local state is device specific.


Most communication between the Kolide Endpoint Agent and the Kolide servers is authenticated with the node key. This key is stored in a local database, and agent presents it to the server.

If the node key is missing, or if the server replies that it is invalid, the agent will use an enrollment secret to connect, and receive a new node key. This enrollment secret is shared between all nodes at an organization, and is stored with the configuration. The node key is specific to the host, and is stored in in the data directory.

As the node key is what identifies the device, it is important to ensure that the image omits it.

Local State

The Kolide Endpoint Agent stores it's state in a set of data directories. On macOS and linux, this directory is /var/kolide-k2/k2device.kolide.com/ On windows it is C:\Program Files\Kolide\Launcher-kolide-k2\data\

As long as the endpoint agent is not running, it is safe to remove this directory. It will be recreated the next time the daemon starts.

Device Association

Kolide uses several methods to assign a device to a person. One of the primary ones is by looking for the person specific tags in the downloaded installer name. As such, you should remove it from disk before saving the image.

Relatedly, if you distribute images with Kolide pre-installed, the automatic device association may not succeed.

Process Overview

A high level mechanism to install the Kolide Agent into an image might be:

  1. Install Package

  2. Remove downloaded package

  3. Stop Daemon (But leave enabled for subsequent restart)

    1. look for a systemd unit named launcher.kolide-k2

  4. Remove data directory

  5. Save device image

To automatically remove these devices from Kolide after 24 hours of inactivity, go to Settings, Device Privacy, and check the box under Data Retention, and click Save Changes.

If you need additional help, feel free to reach out to us via support.

Did this answer your question?