Discover agents with the sensor

The Bairav sensor runs on a Windows host. It finds AI agents, MCP servers, local model runtimes and IDE assistants, reports them to Bairav, and enforces your lifecycle decisions back on the host: block an agent in Bairav and the sensor stops it.

Windows only

The sensor supports Windows with PowerShell 5.1 or later. There is no Linux or macOS sensor. To bring in agents from other platforms, use the gateway, OpenTelemetry traces or security events.

What you need

• The admin role, to create an enrolment token.
• A Windows host that can reach your Bairav deployment over HTTPS.
• Local administrator rights, to install the Windows service.

1. Create an enrolment token

In the console open Settings, Sensor deployment and create a token. You can also call POST /api/admin/enrollment-tokens. The token looks like bst_xxxxxxxx.xxxxxxxx, is shown once, and is stored only as an Argon2id hash. Revoke it from the same page to cut a sensor off.

2. Install

The console builds a package with your server URL and token already filled in (Download sensor, as a zip or as an MSI). The MSI can also be installed unattended:

msiexec /i bairav-sensor.msi SERVERURL="https://your-tenant.example.com" TOKEN="bst_xxxxxxxx.xxxxxxxx" /qn

To try the sensor without installing a service, run the script from the zip once:

.\demo-sensor.ps1 -ServerUrl https://your-tenant.example.com -Token bst_xxxxxxxx.xxxxxxxx -Once -DryRun

Parameter	Meaning
-ServerUrl, -Token	Your deployment and enrolment token.
-IntervalSeconds	How often to report. Default 30.
-GovernanceIntervalSeconds	How often to poll for lifecycle decisions. Default 3.
-Once	Run one cycle and exit.
-DryRun	Print the batch instead of sending it. Nothing leaves the host.
-Background, -Stop	Run detached; stop a detached run.

3. Approve what it found

Discovered agents appear in the Intake queue after the sensor's next reporting cycle. Approve or reject each one. Approving assigns a permanent AGT-###### ID.

What the sensor sends

Everything goes to POST /api/ingest/events with the header X-Sensor-Token, in batches of at most 500 events and 256 KB.

Event type	Carries
heartbeat	The sensor is alive and its version
intake.inventory	Agents, MCP servers, local models and IDEs found on the host
agent.graph	Which agent talks to which model, tool or endpoint
agent.prompts, agent.activity	Masked prompt and activity records
agent.config, inventory.software	Configuration and software inventory
agent.guardrail_block	A block the sensor enforced locally
agent.reactivation_request	A request to lift a hold

Event content is masked at ingest. See Errors and limits for the rate limit and rejection behaviour.

How enforcement flows back

Each cycle the sensor calls GET /api/ingest/governance?device_key=... and applies the result:

• An agent is active unless a reviewer has suspended, blocked or rejected it. Lifting a hold in Bairav re-activates it on the next poll.
• For a held agent the response includes host-level hints (which processes to stop, which port or workflow it owns) so the sensor stops exactly that agent and not every process of the same runtime.
• Guardrail policies attached to an agent are included, so attaching one in Bairav starts enforcing it on the host.

Troubleshooting

Symptom	Check
401 from /api/ingest/events	The token is wrong, revoked or malformed. Create a new one.
429	You exceeded 1,200 events a minute for that token. Honour Retry-After.
Nothing in the Intake queue	Run once with -DryRun to confirm the sensor sees agents, then without it.
Events rejected	The response lists each rejected event with a reason. A wrong schema_version or a timestamp outside the accepted window are the usual causes.