Skip to main content

Levo Sensor for Windows

This guide walks you through installing and configuring Levo.ai’s sensor to capture HTTP traffic on Windows systems/servers.

Prerequisites​

  • Windows 10 or Windows Server 2016 and above
  • SSL termination before the call reaches the application
  • Administrator privileges on the Windows machine
  • Npcap or WinPcap libraries installed. Please talk to us if you want to explore the commercial options for these libraries.

Installation Steps​

1. Install the Npcap Library​

  1. Download the latest Npcap installer from the Npcap website.
  2. Run the installer with administrator privileges.
  3. During installation, select the following options:
    • Install Npcap in WinPcap API-compatible Mode
    • Install Npcap service
    • Do not install the Npcap SDK

2. Download Levo’s Windows Sensor Zip File​

  1. Download the following zip file from our downloads portal:
    • Levoai-Sensor.zip
  2. Extract the contents of Levoai-Sensor.zip
  3. Ensure that all extracted files are placed in the same dedicated directory, e.g., C:\Program Files\Levo\.

3. Configure the Sensor​

Before installing the sensor service, modify the config.json file to match your specific setup:

  1. Open the config.yaml file in a text editor.

  2. Update the following fields:

    • satellite-url: Replace with your actual Levoai Satellite URL.
    • levo-env: Replace with your environment name.
    • levoai-org-id: Replace with your Levo organization ID.
    • levoai-workspace-id: Replace with your Levo Workspace ID.

    Example config.yaml:

        ##############################################################################################
        # PCAP Sensor Configuration Settings (YAML Format)
        # Copyright: Levo Inc., @COPYRIGHT_YEAR@
        ##############################################################################################

        name: "Levoai Sensor"
        display-name: "Levoai Sensor Service"
        description: "Service for running the Levoai Sensor"
        log-file-path: "levoai-service.log"
        exec: "levoai-sensor.exe"
        args: ["apidump"]


        satellite-url: http://collector.levo.ai
        levo-env: staging
        levoai-org-id: ""
        levoai-workspace-id: ""
        rate-limit: 1000
        trace-export-interval: 10
        filter: ""
        path-allow: []
        host-allow: []
        path-exclusions: []
        host-exclusions: []
        memory-hard-limit-mb: 0
        cpu-throttle-percent: 0

4. [Optional] Configure Additional Filters​

  1. Open the config.yaml file in a text editor.

  2. Modify any of these optional flags:

    • trace-export-interval: Set the trace export interval in seconds (default is 10)
    • rate-limit: Specify the number of traces per minute
    • filter: Add a PCAP filter string, e.g., "port 8080 and (not port 8081)"
    • host-allow: Set a host allow regex
    • path-allow: Set a path allow regex
    • host-exclusions: Set a host exclude regex
    • path-exclusions: Set a path exclude regex
    • memory-hard-limit-mb: Set a hard memory limit in MB for the sensor process, enforced by Windows (default is 0/disabled)
    • cpu-throttle-percent: Set a CPU throttle as a percentage of total system CPU capacity across all cores, not a single core (default is 0/disabled)

  3. Configure Sensor for Memory and CPU Resource Limits:

    • For normal/average use cases, use the default configuration
    • For strict resource constraints, download the Low Resource Config File and copy it to the Windows Sensor installation directory
    • To cap resource usage, set memory-hard-limit-mb and/or cpu-throttle-percent in config.yaml — these are enforced at the OS level (Windows Job Objects) and are only supported on the Windows Sensor. Restart the sensor service after changing them for the new values to take effect: 
      levoai-service.exe -service restart

What happens when a limit is hit​

LimitBehavior
memory-hard-limit-mbWindows denies the sensor's next memory allocation once the limit is reached, so the sensor process crashes and exits. The wrapper service detects this and automatically restarts the sensor.
cpu-throttle-percentThe sensor is never restarted or killed for this. Windows simply caps its scheduled CPU time, so it keeps running — just slower — until demand drops back under the limit.

How to confirm this in the logs​

Both limits log when they're first applied, at sensor startup (<pid> is the sensor process's ID, which is different every time it starts):

Starting sensor: C:\...\levoai-sensor.exe [apidump ...]
Job Object memory hard limit set to <memory-hard-limit-mb> MB for pid <pid>
Job Object CPU throttle set to <cpu-throttle-percent>% of total system CPU capacity for pid <pid>

cpu-throttle-percent while it's hitting the cap: the sensor logs a periodic warning, repeated for as long as usage stays at/near the cap. There is no crash and no restart for CPU — the sensor keeps running, just slower, and this line keeps repeating until demand drops below the cap:

Sensor is throttling on CPU: used ~<used-ms>ms of ~<available-ms>ms available in the last <interval> (cpu-throttle-percent=<cpu-throttle-percent>%)

memory-hard-limit-mb when it's actually hit: unlike CPU, this does crash and restart the sensor. Windows denies the next allocation, and the sensor process itself crashes with a Go runtime error before exiting:

fatal error: out of memory

The wrapper service then detects the process is gone (this can take up to memory-check-interval-seconds, since the crash dump itself takes a moment to finish writing out) and automatically restarts it:

Refreshing sensor due to: working set usage reached <working-set> MB (limit <memory-restart-mb>)
Automatic restart requested: working set usage reached <working-set> MB (limit <memory-restart-mb>)
Sensor exited with non-zero status: exit status 1
Starting sensor: C:\...\levoai-sensor.exe [apidump ...]
Job Object memory hard limit set to <memory-hard-limit-mb> MB for pid <pid>

Note the restart threshold above (memory-restart-mb) is automatically kept a safety margin below the configured memory-hard-limit-mb — so in practice, this softer restart is what normally fires first, before the hard limit itself is ever reached.

All of these lines are written to the sensor's log file (log-file-path in config.yaml, default levoai-service.log).

5. Install the Sensor Service​

After configuring the config.json file, you need to install the sensor as a Windows service:

  1. Open PowerShell as an administrator.
  2. Navigate to the directory containing the extracted Levoai sensor files.
  3. Run the following command to install the sensor as a service: 
    levoai-service.exe -service install
  4. Run the following command to check the status of the Levoai service: For PowerShell: 
    Get-Service | Where-Object { $_.Name -like "*Levo*" }
    For Command Prompt (cmd): 
    sc query "Levoai Sensor"
  5. If the service is installed and running successfully, you will see output similar to the following: 
    Status   Name               DisplayName
    Running  Levoai Sensor      Levoai Sensor Service
  6. Run the following command to stop the sensor as a service: 
    levoai-service.exe -service stop
  7. Run the following command to start the sensor as a service: 
    levoai-service.exe -service start
  8. Run the following command to restart the sensor as a service: 
    levoai-service.exe -service restart
  9. Run the following command to uninstall the sensor as a service: 
    levoai-service.exe -service uninstall

6. Troubleshooting​

Ensure Npcap is properly installed and that WinPcap compatibility mode is enabled​

Verify Npcap Installation​
  1. Open a Command Prompt as Administrator.
  2. Run the following command to check if Npcap is installed and running:
sc query npcap
  1. If Npcap is properly installed, you should see an output with STATE: RUNNING.
Verify WinPcap Compatibility Mode​
  1. Open a Command Prompt as Administrator.
  2. Execute the following command:
reg query HKLM\SYSTEM\CurrentControlSet\Services\npcap\Parameters /v WinPcapCompatible
  1. If WinPcap compatibility mode is enabled, you should see the output with WinPcapCompatible REG_DWORD 0x1.

Check Windows Firewall settings​

Ensure the Levo Sensor is allowed to capture traffic.

  1. To check existing firewall rules, execute the below command:
netsh advfirewall firewall show rule name=all
  1. If you cannot find the firewall rule related to the Levo sensor, you can create one:

To create a new inbound rule for the Levo sensor:

netsh advfirewall firewall add rule name="Levo.ai Sensor" dir=in action=allow program="C:\\Program Files\\Levo\\levoai-sensor.exe" enable=yes

Replace "C:\\Program Files\\Levo\\levoai-sensor.exe" with the actual path to the Levo sensor executable.

7. Additional Support​

For additional support, please contact support@levo.ai.

Was this page helpful?