The Sensor Service
Every verb, both units, the files they write, and the ceilings declared where you can read them.
On this page (10)
The Sensor Service Documentation
One command family manages both units the CLI can install. --sensor targets the telemetry service; leaving it off targets the connection service instead.
whisper service install --sensor
Renders the service unit for this machine and installs it. Add --now to start it in the same step.
sudo -E whisper service install --now --sensor
Idempotent: run it again after a newer binary lands and it rewrites the unit, restarting the process only if the unit changed. Keep -E, for the reason on Bind the host.
whisper service start --sensor
Starts an installed service that is not running. The two-step form is whisper service install --sensor then whisper service start --sensor.
whisper service restart --sensor
Applies a configuration change, and picks up an address bound after the service was installed.
sudo -E whisper service restart --sensor
whisper service stop --sensor
Stops the service and leaves the unit, the configuration and the host's identity in place.
whisper service status --sensor
Reports whether the service is installed, whether it is running, and which address it is reporting under.
whisper service uninstall --sensor
Removes the service and its unit. The host keeps its address and stays in your fleet; Upgrade and remove covers giving that up as well.
The two units
| Unit | Carries | Runs as |
|---|---|---|
whisper-sensor | host telemetry and detections | a systemd service on Linux, a service running as LocalSystem on Windows |
whisper-connect | the host's outbound traffic, source-bound to its own address | a systemd service holding no capabilities |
whisper-connect is optional and independent: a host can report telemetry without it, and can carry egress without the sensor. Egress documents it.
Files
| Path | Holds |
|---|---|
/etc/whisper/sensor.json | the sensor's configuration. A fresh install writes {"sensor":{"enabled":true,"dirs":["/var/lib/whisper-sensor/watch"]}} |
/etc/whisper/connect.json | the connection service's configuration |
~/.config/whisper/key | your key, readable only by you |
~/.config/whisper/bound | the marker naming the address this host reports under |
.whisper/config | per-project configuration, for a working directory rather than a machine |
C:\ProgramData\Whisper | configuration on Windows, with the rolling service log under logs\ |
Absent keys in sensor.json mean default, so the file only ever narrows what the sensor does. What the sensor detects lists the keys it accepts.
Environment variables
| Variable | Read for |
|---|---|
WHISPER_DIR | where the installer puts the binary |
WHISPER_KEY, WHISPER_API_KEY | the key, when you would rather not sign in interactively |
There are deliberately no sensor tuning environment variables. What the sensor does is set in sensor.json and, for how hard it works, from the console: see what the sensor costs.
Reading the ceilings
The generated unit declares the sensor's resource ceilings and its own hardening, rather than leaving either to the running process. Read your own machine's:
systemctl cat whisper-sensor
Among them are a CPU ceiling, a soft and a hard memory ceiling, swap held at zero, a low I/O weight and a task ceiling, alongside ProtectHome=read-only, ProtectSystem=full, PrivateTmp, RestrictSUIDSGID and LockPersonality. The unit is the contract: if the sensor asks for more than it declares, the operating system, not the sensor, is what refuses.