Synheart Sensor Agent Overview

​

What is Synheart Sensor Agent?

​

Key Features

• Privacy by Design: Never captures key content, passwords, or screen coordinates
• Behavioral Features: Extracts 16+ behavioral signals from interaction patterns
• HSI Format: Exports data in the Human State Interface (HSI) JSON format
• Transparency: Full visibility into what data is collected via status command
• App Context: Captures foreground application bundle ID per window for task-switch detection (no window titles or content)
• macOS Support: Native integration using Core Graphics event taps
• Windows Support: Native integration using Windows Hooks API

​

Privacy Guarantees

​

Installation

​

From Source

# Clone the repository
git clone https://github.com/synheart-ai/synheart-sensor-agent.git
cd synheart-sensor-agent

# Build in release mode
cargo build --release

# The binary will be at target/release/synheart-sensor

​

Requirements

• Rust: 1.82 or later
• macOS: 10.15 (Catalina) or later
• Windows: 10 or later
• Permissions: Input Monitoring (macOS) or Run as Administrator (Windows)

​

Usage

​

Grant Input Capture Permission

​

macOS

1. Open System Preferences > Security & Privacy > Privacy
2. Select Input Monitoring in the left sidebar
3. Click the lock icon and authenticate
4. Add the synheart-sensor application
5. Restart the application

​

Windows

1. Right-click the synheart-sensor.exe binary
2. Select Run as administrator
3. Or launch your terminal (Command Prompt / PowerShell) as Administrator before running the binary

​

Commands

# Start capturing behavioral data (default: --sources all)
synheart-sensor start

# Start with specific sources
synheart-sensor start --sources keyboard
synheart-sensor start --sources mouse
synheart-sensor start --sources keyboard,mouse
synheart-sensor start --sources all

# Pause / resume collection
synheart-sensor pause
synheart-sensor resume

# Show current status and statistics
synheart-sensor status

# Display privacy declaration
synheart-sensor privacy

# Show resolved configuration
synheart-sensor config

# Run as an HTTP server (feature-gated; requires `--features server` build)
synheart-sensor serve

​

Data Flow

sensor-agent (raw events) --> Synheart runtime (SensorTranslator → FeatureSet)

​

Configuration

• macOS: ~/Library/Application Support/synheart-sensor-agent/config.json
• Windows: %APPDATA%\synheart-sensor-agent\config.json

{
  "sources": {
    "keyboard": true,
    "mouse": true
  },
  "data_path": "~/.local/share/synheart-sensor-agent",
  "paused": false
}

​

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Synheart Sensor Agent                       │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐                     ┌─────────────┐       │
│  │  Collector  │────────────────────▶│ Raw Events  │       │
│  │   (macOS)   │                     │  (channel)  │       │
│  └─────────────┘                     └─────────────┘       │
│         │                                                  │
│         ▼                                                  │
│  ┌─────────────┐                                           │
│  │Transparency │                                           │
│  │    Log      │                                           │
│  └─────────────┘                                           │
└─────────────────────────────────────────────────────────────┘
         Pure sensor — windowing, features, and sessions handled
         by the Synheart Runtime

​

Troubleshooting

​

macOS: “Input Monitoring permission not granted”

1. Open System Preferences > Security & Privacy > Privacy
2. Select Input Monitoring
3. Ensure the application is in the list and checked
4. If already checked, remove and re-add the application
5. Restart the application

​

Windows: “Administrator privileges required”

1. Right-click the terminal or binary and select “Run as administrator”
2. If using PowerShell, launch it with elevated privileges
3. Restart the application

​

No events being captured

• Ensure you’re actively typing or moving the mouse
• Check that the correct sources are enabled (--sources all)
• Verify permission is granted with synheart-sensor status
• macOS: Confirm Input Monitoring permission in System Preferences
• Windows: Confirm the process is running as Administrator

​

Resources

• GitHub: synheart-ai/synheart-sensor-agent
• crates.io: synheart-sensor-agent
• docs.rs: synheart-sensor-agent

​

License