# The Sensor Service

> Reference for whisper service: install, start, stop, restart, status, uninstall; the sensor and connection units; their config files and ceilings.

*Source: https://www.whisper.security/docs/endpoint/install/service*

---
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.

```bash
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](/docs/endpoint/install/enroll).

## `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.

```bash
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](/docs/endpoint/install/remove) covers giving that up as well.

## The two units {#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](/docs/network/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](/docs/endpoint/operate/detections) 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](/docs/endpoint/operate/footprint).

## 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:

```bash
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.