Skip to main content

​
Linux Installation

Install OISP Sensor on any Linux distribution with native packages or standalone binary.
Download and install the binary: 
# Download
curl -fsSL https://github.com/oximyhq/sensor/releases/latest/download/oisp-sensor-x86_64-unknown-linux-gnu.tar.gz | tar xz

# Install
sudo mv oisp-sensor /usr/local/bin/
sudo chmod +x /usr/local/bin/oisp-sensor

# Set capabilities (allows running without full root)
sudo setcap cap_sys_admin,cap_bpf,cap_perfmon,cap_net_admin+ep /usr/local/bin/oisp-sensor

# Verify
oisp-sensor --version

​
Installation Methods

​
Method 1: Package Manager

Install using your distribution’s native package manager.

    ​
    Method 2: Binary Installation

    Portable binary installation without package manager: 
    # Download binary
curl -fsSL https://github.com/oximyhq/sensor/releases/latest/download/oisp-sensor-x86_64-unknown-linux-gnu.tar.gz | tar xz

# Install
sudo mv oisp-sensor /usr/local/bin/
sudo chmod +x /usr/local/bin/oisp-sensor

# Set capabilities for non-root operation
sudo setcap cap_sys_admin,cap_bpf,cap_perfmon,cap_net_admin+ep /usr/local/bin/oisp-sensor
    Manual systemd service setup: 
    # Create service file
sudo tee /etc/systemd/system/oisp-sensor.service > /dev/null <<EOF
[Unit]
Description=OISP Sensor - AI Activity Monitoring
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/oisp-sensor record --output /var/log/oisp/events.jsonl
Restart=on-failure
RestartSec=10

# Capabilities
AmbientCapabilities=CAP_SYS_ADMIN CAP_BPF CAP_PERFMON CAP_NET_ADMIN
CapabilityBoundingSet=CAP_SYS_ADMIN CAP_BPF CAP_PERFMON CAP_NET_ADMIN

# Security
NoNewPrivileges=no
ProtectSystem=strict
ReadWritePaths=/var/log/oisp
ProtectHome=read-only
PrivateTmp=true

# Resource limits
LimitMEMLOCK=infinity
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

# Create log directory
sudo mkdir -p /var/log/oisp
sudo chmod 755 /var/log/oisp

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable oisp-sensor
sudo systemctl start oisp-sensor

    ​
    Verify Installation

    After installation, verify OISP Sensor is working:

    ​
    1. Check Binary Version

    oisp-sensor --version

    ​
    2. Run System Check

    oisp-sensor check
    Expected output: 
    OISP Sensor System Check
========================

Platform: linux x86_64 (supported)

Kernel Version:    6.8.0 [OK]
BTF Support:       /sys/kernel/btf/vmlinux [OK]
eBPF Filesystem:   /sys/fs/bpf [OK]
Permissions:       CAP_BPF+CAP_PERFMON set [OK]

SSL Libraries:
  /usr/lib/x86_64-linux-gnu/libssl.so.3 [FOUND]

Result: READY

    ​
    3. Test Capture

    Run a simple test to verify capture works: 
    # Start sensor in one terminal
sudo oisp-sensor record --output /tmp/test.jsonl

# In another terminal, make an HTTPS request
curl -s https://api.openai.com/v1/models > /dev/null

# Stop sensor (Ctrl+C) and check events
cat /tmp/test.jsonl | jq -r '.event_type' | sort | uniq -c

    ​
    System Requirements

    Before installing, verify your system meets the requirements:

    ​
    1. Kernel Version

    uname -r  # Should be >= 5.0 (5.8+ recommended)

    ​
    2. BTF Support

    ls /sys/kernel/btf/vmlinux  # Should exist
    If BTF is missing:

      ​
      3. BPF Filesystem

      ls /sys/fs/bpf  # Should exist

      ​
      4. OpenSSL Library

      ldconfig -p | grep libssl  # Should show libssl.so.3 or libssl.so.1.1

      ​
      ARM64 (aarch64)

      OISP Sensor fully supports ARM64 (Graviton, Raspberry Pi, etc.): 
      # Download ARM64 binary
curl -fsSL https://github.com/oximyhq/sensor/releases/latest/download/oisp-sensor-aarch64-unknown-linux-gnu.tar.gz | tar xz

# Install
sudo mv oisp-sensor /usr/local/bin/
sudo chmod +x /usr/local/bin/oisp-sensor
sudo setcap cap_sys_admin,cap_bpf,cap_perfmon,cap_net_admin+ep /usr/local/bin/oisp-sensor

      ​
      Troubleshooting Installation

      ​
      ”Permission denied” when running

      Run with sudo or set capabilities: 
      sudo setcap cap_sys_admin,cap_bpf,cap_perfmon,cap_net_admin+ep /usr/bin/oisp-sensor

      ​
      “BTF not found”

      Install kernel headers: 
      # Ubuntu/Debian
sudo apt-get install linux-headers-$(uname -r)

# RHEL/Fedora
sudo dnf install kernel-devel

      ​
      “No SSL libraries found”

      Install OpenSSL: 
      # Ubuntu/Debian
sudo apt-get install libssl3

# RHEL/Fedora
sudo dnf install openssl-libs
      See Troubleshooting Guide for more issues.

      ​
      Uninstallation

        ​
        Next Steps

        1. Quick Start — See events in 5 minutes
        2. Running as a Service — Configure systemd service
        3. Production Deployment — Deploy to production
        4. Troubleshooting — Solve common issues