valet-agent 2026.1.20

DeviceValet Linux Agent - Fleet management daemon for Linux desktops, servers, and IoT devices

DeviceValet Linux Agent

Fleet management daemon for Linux desktops, servers, and IoT devices. Part of the DeviceValet ecosystem.

Features

• Device Enrollment — One-command enrollment via token
• System Telemetry — CPU, memory, disk, GPU, thermals, network
• WiFi Geolocation — Location via BeaconDB (privacy-respecting)
• Real-time Commands — MQTT-based instant command execution
• Package & Service Inventory — Track installed software
• Systemd Integration — Runs as a background service

Quick Start

Install from PyPI

# Install with pipx (recommended)
pipx install valet-agent

# Or with pip
pip install valet-agent

# Or with uv
uv tool install valet-agent

Enroll Your Device

# Get an enrollment token from your DeviceValet dashboard, then:
sudo valet-agent enroll --server https://valet.example.com --token YOUR_TOKEN

# Start the agent
sudo valet-agent run

Install as System Service

# Copy the systemd unit file
sudo cp valet-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now valet-agent

# Check status
sudo systemctl status valet-agent
sudo journalctl -u valet-agent -f

CLI Commands

valet-agent --help              # Show all commands

# Enrollment
valet-agent enroll              # Enroll device with server
  --server URL                  # Server URL (required)
  --token TOKEN                 # Enrollment token (required)
  --mqtt-url URL                # Override MQTT broker URL

# Agent Operations
valet-agent run                 # Start the agent daemon
  --config-dir PATH             # Config directory (default: /etc/valet-agent)
  --once                        # Single check-in then exit

# Diagnostics
valet-agent status              # Show enrollment & connection status
valet-agent info                # Display detailed hardware info
  --json                        # Output as JSON
  --packages                    # Include installed packages
  --services                    # Include running services

Configuration

After enrollment, configuration is stored in /etc/valet-agent/agent.env:

Variable	Description	Default
VALET_SERVER_URL	DeviceValet server URL	Set during enrollment
VALET_AUTH_TOKEN	Device authentication token	Set during enrollment
VALET_DEVICE_ID	Unique device identifier	Set during enrollment
VALET_CHECKIN_INTERVAL_SECONDS	Telemetry interval	300
VALET_REPORT_LOCATION	Report WiFi-based location	true
VALET_REPORT_PACKAGES	Include package inventory	true
VALET_REPORT_SERVICES	Include running services	true
VALET_MQTT_ENABLED	Enable real-time commands	true
VALET_BEACONDB_ENABLED	Use BeaconDB for location	true
VALET_BEACONDB_CONTRIBUTE	Contribute to BeaconDB	true

Remote Commands

The agent responds to commands sent via MQTT:

Command	Description
lock	Lock the screen (requires display session)
ring	Play sound to locate device
message	Display desktop notification
reboot	Schedule system reboot
shutdown	Schedule system shutdown
run_script	Execute approved scripts
install_package	Install system package (apt/pacman)

Docker Deployment

For containerized environments or server monitoring:

services:
  valet-agent:
    image: ghcr.io/supported-systems/valet-agent:latest
    environment:
      VALET_SERVER_URL: https://valet.example.com
      VALET_AUTH_TOKEN: ${DEVICE_TOKEN}
    restart: unless-stopped
    volumes:
      # Required for hardware identification
      - /etc/machine-id:/etc/machine-id:ro
      - /sys/class/dmi/id:/sys/class/dmi/id:ro
      # Optional: for full system metrics
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro

Supported Distributions

Distribution	Package Manager	Notes
Arch Linux	pacman	Full support
Debian 11+	apt/dpkg	Full support
Ubuntu 22.04+	apt/dpkg	Full support
Fedora 38+	dnf	Full support
RHEL/Rocky 9+	dnf	Full support
Alpine	apk	Container-only

Requires Python 3.10+ and systemd for service management.

Development

# Clone the repository
git clone https://github.com/supported-systems/devicevalet.git
cd devicevalet/agent-linux

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/valet_agent

# Linting
ruff check src/
ruff format src/

Telemetry Data

The agent collects and reports:

• Hardware: Manufacturer, model, serial number
• System: OS version, kernel, uptime, hostname
• Resources: CPU usage, memory, disk space
• Network: IP address, MAC address, connection type
• Extended (in platform_data):
  • CPU model, cores, frequency, cache
  • GPU info (name, driver, VRAM)
  • Thermal sensors
  • Installed packages
  • Running systemd services

Privacy

• No data is sent to third parties
• WiFi geolocation uses BeaconDB (opt-in contribution)
• All communication is over HTTPS/WSS
• Device tokens are stored with 0600 permissions

License

MIT License - see LICENSE for details.

Links

• Documentation
• GitHub Repository
• Issue Tracker
• Changelog