Installation

The Koban agent is a macOS menubar app that watches package managers and config directories, then syncs observations to Fleet when enrolled.

Requirements

• macOS 26 or later
• Outbound HTTPS to your Fleet endpoint (when enrolled)

Download the latest release

Download the latest macOS release from the koban-agent GitHub Releases page.

Download the latest version, open it, and move Koban Agent to Applications.

Build from source

Clone and build from the koban-agent repository:

git clone https://github.com/iaserrat/koban-agent
cd koban-agent
# Follow README for build and install steps

First run

1. Launch the agent from the menubar.
2. Confirm watched paths and sync settings in the agent configuration.
3. Optionally enroll in Fleet with your Fleet URL and a short-lived enrollment token. The agent generates a device key, registers the device, and stores its identity material in the macOS Keychain. Steady-state sync then authenticates with your tenant sensor token, or with a device client certificate when a self-hosted Fleet requires mTLS.

Sync configuration

Local configuration lives at ~/.config/koban/koban.yaml. The sync section points the agent at your Fleet endpoint and controls upload limits.

sync:
  endpoint: https://fleet.example.com
  enrollmentToken: short-lived-bootstrap-token   # one-time, registers the device
  sensorToken: your-tenant-sensor-token          # authenticates steady-state sync
  maxBatchBytes: 524288
  maxBatchEvents: 500

Use enrollmentToken only to register a new Mac. Steady-state sync authenticates with the tenant sensorToken, which you create in Fleet and distribute through your MDM. Self-hosted enterprise deployments can require mTLS instead, where the device certificate issued during enrollment authenticates sync and the sensor token is not used.

See Authentication for the full registration, sensor token, and mTLS flow.

The endpoint can be Koban Fleet or any backend that implements Koban Sensor Protocol v1.

What gets inventoried

The agent reads canonical paths on disk: lockfiles, package receipts, and AI tooling configs (MCP servers, hooks, skills, Cursor rules, and similar). No kernel extensions or network taps are required.

See Coverage on the homepage for the full list.

Next steps

After install, define fleet rules and enroll Macs in Fleet so observations and findings sync centrally.