Cross-platform agentic system monitoring
IronMonitor is a powerful, cross-platform hardware monitoring utility designed primarily for AI agents and interactive interfaces. It provides deep insights into CPUs, GPUs, memory, disks, motherboards, and network interfaces across Windows, Linux, and macOS.
Primary Usage Modes
| Mode | Command | Description |
|---|---|---|
| ๐ค AI Agent | amon / ironmon ai |
Natural language queries, MCP server for Claude, tool manifests for LLMs |
| ๐ป CLI | ironmon <component> |
Command-line monitoring with JSON output for scripting |
| ๐ฅ๏ธ TUI | ironmon tui |
Interactive terminal dashboard with real-time graphs and selectable themes |
| ๐ช GUI | ironmon gui |
Native desktop application with egui |
Overview
IronMonitor reads hardware across Linux, Windows and macOS. What it reads varies by platform and by machine, and it is built to say which โ see What IronMonitor cannot do.
- ๐ Hardware Profile Inspector: NVIDIA Profile Inspector / Intel XTU / AMD Ryzen Master / nvme-cli equivalents โ read & (selectively) write driver profiles, per-app NVIDIA DRS data, CPU power limits, NVMe Get-Features, EDID/XMP/EXPO, with audit-logged apply layer. See
ironmon profile --help. - ๐ฎ GPU Monitoring: NVIDIA, AMD, and Intel GPUs with utilization, memory, temperature, power, and process tracking
- ๐ป CPU Monitoring: Per-core metrics, frequencies, temperatures, and hybrid architecture support
- ๐ง Memory Monitoring: RAM, swap, bandwidth, and latency tracking
- ๐พ Disk Monitoring: I/O operations, throughput, queue depth, SMART attributes, and NVMe controller data, with health derived from what the drive actually reports
- ๐ง Motherboard Monitoring: System information, BIOS version, and hardware sensors
- ๐ Process Monitoring: System-wide process tracking with GPU attribution
- ๐ Network Monitoring: Interface statistics, bandwidth rates, and network health
- ๏ฟฝ Network Tools: nmap-style port scanning, ping, traceroute, DNS lookup
- ๐ Audio Monitoring: Audio device enumeration, volume levels, and mute states
- ๐ถ Bluetooth Monitoring: Adapter and device enumeration, battery levels, connection states
- ๐ฅ๏ธ Display Monitoring: Connected displays, resolutions, refresh rates, and scaling
- ๐ USB Monitoring: USB device enumeration, device classes, and connection topology
Interfaces:
- ๐ค AI Agent: Natural language queries, MCP server for Claude Desktop, tool manifests for all major LLMs
- ๐ป CLI: Structured command-line output with JSON support for scripting and automation
- ๐ฅ๏ธ TUI: Beautiful terminal interface with real-time graphs, selectable themes, and integrated AI chat
- ๐ช GUI: Native desktop application with multiple themes and visualizations
What IronMonitor cannot do
Every item here is something the project has checked and can point at, not a disclaimer. ironmon's whole design position is that an absence reported honestly beats a confident wrong answer, and that applies to its own capabilities.
Readings that are not what their name suggests
- CPU frequency on Windows is nominal, not live. It comes from
CallNtPowerInformation(ProcessorInformation), and on the development machine it read exactly 4400 MHz while sixteen busy threads took system idle from 79.7% to 11.4%. Treat it as the rated clock. There is no unelevated live figure. - CPU percentages on Linux and macOS are averages since boot, derived from
cumulative tick counters, not instantaneous rates. The TUI and GUI graphs are
built from repeated samples and do show change over time; a single
ironmon cpuis not a snapshot of this second. - macOS has no GPU, power or temperature readers.
IronMonitor::snapshot()fails there because it requires all of them.IronMonitor::cpu(),memory()anduptime()work.
Code that compiles everywhere and has not run everywhere
- The Windows ATA SMART parser has never met a SATA drive. It is tested only against buffers this project constructed. The development machine has NVMe only, where the path correctly declines.
- The Linux profile writers have never executed.
scaling_governor,perf_levelandgt_max_freq_mhzare written by inspection and checked by the compiler and CI. No Linux machine in this project's history has run them. - macOS readers are checked for plausibility, not correctness. CI asserts the numbers are in sensible ranges. Nobody has compared them against Activity Monitor.
Things that are structurally out of reach
ironmon tunecan apply settings and currently cannot verify them. The verification loop is implemented and its metric registry is deliberately empty: every candidate metric was checked and none survived. Applying a setting therefore reportsunverifiablerather than an improvement. That is the honest output, not a placeholder โ seesrc/tuning/verify.rs.- Intrusion detection watches socket tables, not traffic. IronMonitor cannot see packet contents, so it detects what is listening and what changed against a baseline. File integrity covers an explicit watchlist, not a filesystem sweep, and choosing that watchlist is the part that decides whether it is useful.
- A first intrusion scan cannot report a machine clean. It returns
no_baselineand records one. A baseline taken after a compromise records the compromise. - The ontology declares entities no resolver reads yet. Those resolve as
unavailablewith the reason "no resolver bound on this build" rather than being omitted, so an agent can tell "this machine has no such device" from "IronMonitor cannot read this".ironmon snapshot --validatereports the coverage.
Nothing here writes without being told twice
Applying a setting requires --confirm and is recorded in an audit log. The
library never elevates itself. The intrusion detector observes only: it will not
block a connection, kill a process, or quarantine a file.
Features
Multi-Vendor GPU Support
- NVIDIA: Full NVML integration for all CUDA-capable GPUs (GeForce, Quadro, Tesla, Jetson)
- AMD: ROCm/sysfs support for RDNA/CDNA architectures (Radeon, Instinct)
- Intel: i915/xe driver support for Arc, Iris Xe, and Data Center GPUs
- Unified API: Single interface for all GPU vendors with vendor-specific capabilities
Comprehensive Metrics
GPU Metrics:
- Utilization (graphics, compute, video engines)
- Memory usage (used, free, total, bandwidth)
- Clock frequencies (graphics, memory, streaming multiprocessor)
- Temperature sensors (GPU, memory, hotspot)
- Power consumption (current, average, limit, TDP)
- PCIe bandwidth and generation
- Per-process GPU memory attribution
CPU Metrics:
- Per-core utilization and frequency
- Temperature sensors
- Cache sizes (L1, L2, L3)
- Thread topology
- Power states
Memory Metrics:
- Total, used, free, available
- Swap usage
- Page faults
- Memory bandwidth
Disk Metrics:
- Read/write bytes and operations
- Queue depth and latency
- SMART attributes
- Device information
Network Metrics:
- Per-interface RX/TX statistics
- Bandwidth rates
- Packet errors and drops
- Link speed and state
Process Monitoring with GPU Attribution
IronMonitor uniquely correlates system processes with GPU usage across all vendors:
use ;
let gpu_collection = auto_detect?;
let mut monitor = with_gpus?;
// Get processes sorted by GPU memory usage
let gpu_procs = monitor.processes_by_gpu_memory?;
for proc in gpu_procs.iter.take
AI Agent for System Analysis
Ask questions through a configured model backend. The built-in agent calls read-only monitoring tools to obtain evidence and follow-up observations:
use ;
use RunControl;
let config = auto_detect?;
let mut agent = new?;
let response = agent.ask_with_control?;
println!;
Features:
- Native tool calls through OpenAI Responses, Anthropic Messages, Ollama chat, and compatible Chat Completions servers such as IronWorks
- Bounded tool rounds, deadlines, argument validation, queues and result sizes
- Background GUI queries with visible tool activity and cancellation
- Fresh evidence on repeated questions; live answers bypass the question cache
- See docs/AI_AGENT.md for the agent itself, AI_INTEGRATION.md for model providers, and AGENTS.md for driving ironmon programmatically
Use-case tuning
ironmon tune works out what the machine is being used for โ AI training, AI
inference, gaming, interactive, idle โ and recommends the hardware profile
settings that suit it. --watch N turns it into the automatic server.
Use case: ai_training (confidence 90%, from signals)
ยท busiest GPU at 97% utilisation; CPU at 22%; AI workload detected (pytorch) doing training
ยท an AI framework was identified in a running process
Recommended (1):
Active Power Scheme [Safe]
381b4222-... -> 8c5e7fda-...
basis: the driver's own choice "High performance" for this setting
why: AI work is bursty on the CPU while the GPU waits on it; core parking
adds latency to every dispatch
Two properties worth knowing before trusting it.
It recommends and writes nothing by default. Applying needs --apply and
--confirm, goes through the audited apply layer, and is capped below the risk
tier that covers power, thermal and voltage writes โ --max-risk dangerous is
rejected, not clamped.
Every proposed value comes from what the driver itself declared, never from a
model. A language model may classify the workload, where being wrong costs a
suboptimal profile; it does not choose values, because a number with no
provenance cannot be checked against anything the hardware said. basis on each
recommendation records where the value came from, and a setting whose provider
enumerates no choices is skipped with a reason rather than given a
plausible-looking one.
AI Agent Discoverability & Hardware Ontology
IronMonitor is designed from the ground up to be discoverable by AI agents. It provides a structured hardware ontology that allows agents to understand what monitoring capabilities are available and how to query them.
Hardware Ontology
Every value IronMonitor can report has a stable dotted id, a unit, and โ the part that matters โ a provenance saying whether it was measured, taken from a specification, derived, or is unavailable here. No model or library linkage is needed; it is a command:
A value that could not be read carries no value at all, and always says why โ
so an agent can tell an absent device from an unimplemented reader, and never
mistakes a plausible constant for a live reading:
Coverage is deliberately reported rather than claimed. ironmon describe prints
the entity count, and the ontology currently names 134 entities across 12
domains โ cpu (including cache topology), gpu, memory (including per-slot DIMM
topology, NUMA layout and ECC error counts), disk (including SMART, health and NVMe endurance), network, power,
thermal, process, system (including virtualization posture), board (including firmware inventory and TPM state), pci
(including negotiated versus maximum PCIe link width and speed) and usb. On one
desktop those expand to 780 resolved readings and 432 that are
unavailable-with-a-reason.
Some of those readings are worth having precisely because nothing else reports
them. pci.{addr}.link.width against pci.{addr}.link.max_width on the
development machine shows a card negotiated at x8 in a x16-capable slot โ
half its bandwidth, and not an error anywhere in the system.
It does not yet name everything the library can read. IronMonitor has around 88
subsystem modules, and the ones without ontology entities โ NUMA topology, RAPL,
sensors, virtualization, EDAC, and others โ are reachable through the library and
the cli subcommands but not yet through describe, get and snapshot. That
gap is being closed in phases, and a phase ships only when its resolver can state
a true provenance for every field. An id that resolves to a confident guess is
worse for an agent than one that does not exist.
The ontology tests the ontology
tests/ontology_conformance.rs names nothing it checks. It asks the ontology
what exists, resolves it, and asserts the rules the ontology documents about
itself โ every declared entity reachable, every reading traceable to the schema,
every absence carrying a reason, no nullable: false entity resolving to null,
every value's JSON type matching its unit, nothing outside its declared range,
and no enum's Unknown dressed up as a measurement.
A domain added later is covered by all of it on the commit that adds it, with no edit to the file โ which matters because the failure mode of a hand-written suite is that the newest reader is the least tested one. It found three defects on its first run, including an entity that had been declared since the ontology was written and that no resolver had ever filled.
See AGENTS.md for the full contract: exit codes, the write surface, and how to read the TUI and GUI without a terminal or display.
The older
ironmonitor::ai_api::HardwareOntologyis superseded. It carries no provenance, cannot resolve an id to a value, and no command exposes it.
use HardwareOntology;
let ontology = complete;
println!;
Tool Discovery
AI agents can enumerate all available monitoring tools with their schemas:
use ;
let api = new?;
let tools: = api.list_tools;
for tool in &tools
MCP Server (Model Context Protocol)
For seamless integration with Claude Desktop and other MCP-compatible AI systems:
Configure in Claude Desktop's claude_desktop_config.json:
Multi-Format Tool Export
Export tool definitions in formats optimized for different AI platforms:
This enables AI agents to:
- Discover available hardware monitoring capabilities at runtime
- Understand the data types and units for each metric
- Query system state using structured tool calls
- Reason about hardware relationships through the ontology
Installation
From crates.io
That installs both binaries, ironmon and amon. Default features are full,
which includes the GUI, so on Linux the build needs system development packages:
As a library, where the GUI and CLI stacks are usually unwanted:
[]
= { = "7.0", = false, = ["cpu", "io", "network"] }
Both the Cargo package and Rust library are named ironmonitor. Update any
existing ironmonlib imports to ironmonitor:
use disk;
From Source
# Clone the repository
# Build with all GPU vendor support
# Or build for specific vendors
Binary Aliases
The CLI provides two binary names optimized for different use cases:
ironmon - Full IronMonitor
Subcommands for specific metrics:
# No subcommand: launches the GUI, or the TUI if built without the `gui` feature
# Launch the TUI explicitly
# Monitor specific components
# Peripheral hardware
# Watch mode: continuously monitor devices (press 'q' to quit)
#### `amon` - AI Monitor
# Build both binaries
Feature Flags
nvidia- NVIDIA GPU support via NVMLamd- AMD GPU support via sysfs/DRMintel- Intel GPU support via i915/xe driversapple- Apple Silicon support (M-series) viapowermetricscpu- Enhanced CPU monitoring (per-core, clusters, power states)npu- NPU/ASIC monitoring (ANE, Intel NPU, AMD AI Engine)io- I/O controller monitoring (PCIe, NVMe, USB, Thunderbolt)network- Network silicon monitoring (WiFi, Ethernet, offload engines)cli- Command-line interface and TUIgui- Desktop GUIfull- All features enabled (the default)
Every feature builds in isolation, and CI checks each one that way on every push โ
--all-features cannot catch a feature that only compiles because another supplies
what it is missing. Built without gui, ironmon with no subcommand launches the
TUI instead of the desktop window.
Quick Start
GPU Monitoring
use GpuCollection;
CPU Monitoring
use CpuMonitor;
let mut monitor = new?;
let info = monitor.update?;
println!;
for in info.cores.iter.enumerate
Memory Monitoring
use MemoryMonitor;
let mut monitor = new?;
let info = monitor.update?;
println!;
println!;
Disk, SMART and NVMe Monitoring
use ;
for device in enumerate_disks?
health() derives from SMART rather than from the device merely existing, so a
drive whose counters cannot be read reports Unknown instead of Healthy.
On Windows, NVMe drives are read from the controller itself โ Identify Controller
and the SMART/Health log page, via DeviceIoControl โ so temperature, power-on
hours, wear, controller id, namespace count and critical warnings all resolve
without elevation.
SATA drives have no such log page, but the storage driver will issue SMART READ
DATA on their behalf โ IOCTL_STORAGE_PREDICT_FAILURE โ so their attribute table,
failure prediction and sector counts also resolve without elevation. Note that
this path has not yet been run against real ATA hardware; see
docs/DISK_MONITORING.md.
USB bridges that tunnel neither fall back to WMI, where
Get-StorageReliabilityCounter does require elevation. Unelevated, their identity
fields still resolve while the counters come back None.
Drives that reach the WMI fallback โ no longer NVMe or SATA, but still USB bridges
and anything else the two passthroughs decline โ are served from one collector
sweep shared across every drive and accessor for two seconds. A sweep is around a
second, so this matters. Construct a ironmonitor::smart::SmartMonitor directly if
you need a guaranteed-fresh one.
See cargo run --all-features --example disk_monitor for the full surface.
Network Monitoring
use NetworkMonitor;
let mut monitor = new?;
let interfaces = monitor.interfaces?;
for iface in interfaces
Network Diagnostic Tools (nmap, traceroute, ping style)
IronMonitor includes network diagnostic utilities inspired by popular CLI tools:
use ;
use Duration;
// Ping a host
let result = ping?;
println!;
// DNS lookup
let ips = dns_lookup?;
for ip in ips
// Traceroute
let hops = traceroute?;
for hop in &hops.hops
// Port scan (nmap-style TCP connect scan)
let ports = ;
let results = scan_ports?;
for r in results
// Quick port check (netcat-style)
let open = check_port?;
println!;
AI Agent CLI and API
Peripheral Hardware Monitoring
IronMonitor provides cross-platform monitoring for audio, Bluetooth, display, and USB devices:
Audio Devices
use AudioMonitor;
let mut monitor = new?;
let devices = monitor.devices;
for device in devices
// Get master volume (0-100)
if let Some = monitor.master_volume
Bluetooth Devices
use BluetoothMonitor;
let mut monitor = new?;
// List adapters
for adapter in monitor.adapters
// List connected/paired devices
for device in monitor.devices
Display/Monitor Information
use DisplayMonitor;
let monitor = new?;
for display in monitor.displays
USB Devices
use UsbMonitor;
let monitor = new?;
for device in monitor.devices
IronMonitor includes a lightweight AI agent that can answer questions about your system in natural language:
Command Line Interface
# Quick single queries with amon
# Interactive AI session
# You: What's my GPU doing?
# ๐ค Agent: Your GPU is currently at 45% utilization...
# Or use ironmon ai subcommand
Programmatic Usage
use ;
use RunControl;
let config = auto_detect?;
let mut agent = new?;
let response = agent.ask_with_control?;
println!;
Agent Features
- Natural Language: Ask questions in plain English
- System Aware: Reads the same hardware metrics the CLI does, with the same caveats โ CPU percentages on Linux and macOS are averages since boot, not instantaneous rates
- Multiple Backends: Automatic detection of local and remote AI models
- Local by Default: Prefers backends that keep telemetry on your machine
- Fresh Evidence: Repeated questions obtain fresh tool results rather than cached answers
- Interactive Mode: Multi-turn conversations about your system
A backend is required. There is no offline fallback: the agent needs an inference backend and reports an error if none is available. Start an IronWorks server, install one of the CLI tools below, or configure an API key.
Monitoring tools for agents
The MCP catalogue and manifests expose 62 registered tools. The built-in agent uses a 51-tool read-only allowlist; hardware writes and benchmarks are excluded from automatic tool calling.
| Tool | Evidence returned |
|---|---|
get_observation_snapshot |
Collector-backed readings with provenance, sample time and freshness |
get_collector_health |
Collector status, generation and provider health |
query_metric_history |
Bounded session history, aggregation, gaps and truncation |
query_events |
Retained monitoring events with filters |
inspect_process |
Process identity, sampled metrics, history and attributable connections |
list_connections |
Connection observations with provider errors and sample time |
check_endpoint |
Bounded DNS, TCP, TLS and HTTP diagnostics |
describe_entities |
Versioned schema, IDs, templates, units and constraints |
inspect_services |
Windows services or Linux systemd units |
query_os_events |
Windows event logs or Linux journald records |
Unavailable readings have a reason and no value. Observation timestamps include
sampled_at_ms and a matching sampled_at_utc; history remains bounded in memory.
A single sample cannot establish a throughput rate. Services and OS events report
unavailable on platforms without a supported provider.
The model must support the selected backend's tool protocol. IronWorks can recover an exact JSON call containing only a registered read-only name and arguments; it does not repair malformed fragments. Unexecuted tool-call text is rejected, and backend output-token limits are explicitly marked.
Local testing covered all 62 tool routes, ten manifest formats and fourteen protocol/input checks. Native provider protocols have deterministic fixtures. Live model testing also found failures: Ollama's installed small model inconsistently followed tool schemas, and IronWorks refused the tested Qwen2 1.5B and Gemma2 2B checkpoints because their tool chat templates were unsupported. The larger model completed monitoring queries but also returned off-topic and truncated answers in a run with nearly full system memory. Model prose is not a substitute for checking tool provenance and timestamps.
See AI_INTEGRATION.md for provider setup, tool parameters, bounds and platform coverage, and AGENTS.md for the reading contract.
Supported Backends
Built-in engine:
- IronWorks โ the default. Pure-Rust
inference engine, reached over its OpenAI-compatible server on
localhost:8080. This is the only engine ironmon ships against; everything below is an external provider you install or sign in to separately.
External servers:
- TensorRT-LLM - NVIDIA optimized inference (requires Triton server)
- vLLM - High-performance serving with PagedAttention
- Ollama - Easy local model management (recommended for beginners)
- LM Studio - User-friendly GUI for local models
- llama.cpp - GGUF models via the
llama-cliexecutable. Auto-detected onPATH, but must be configured with a model path before use.
Command-line tools (driven as subprocesses; no API key needed since the tool is already authenticated):
ollama,claude,codex,gemini
Remote API Backends:
- OpenAI API - GPT models (requires
OPENAI_API_KEY) - Anthropic Claude - Claude models (requires
ANTHROPIC_API_KEY) - Azure OpenAI - Enterprise OpenAI (requires
AZURE_OPENAI_API_KEY)
Where your telemetry goes
Selection prefers backends that infer on your machine, so a hosted provider is only chosen when nothing local is running.
Note that a local process is not the same as local inference: of the CLI tools,
only ollama runs the model on your hardware. claude, codex and gemini relay
your prompt โ including the system metrics embedded in it โ to their vendor, exactly
as the corresponding remote API would.
Backend Configuration
# List available backends
# [*] Available AI Backends:
# 1. IronWorks (Built-in Engine) [+] running on localhost:8080
# 2. Ollama (Local Server) [+] running
# 3. Claude CLI [+] found on PATH
# Automatic backend detection (default)
# [*] Using backend: IronWorks
# Question: What's my GPU temperature?
# ...
# Configure via environment variables (remote APIs only)
# For OpenAI
# For Anthropic
# Or start local inference servers
# TensorRT-LLM via Triton # TensorRT (NVIDIA only)
# LM Studio GUI โ Start Server # LM Studio on port 1234
Programmatic Backend Selection
use ;
// Auto-detect best backend
let config = auto_detect?;
// Or use specific backend
let config = with_backend_type?;
// Or custom configuration
let backend = openai;
let config = with_backend;
let mut agent = new?;
Example Queries:
- "What's my GPU temperature and is it safe?"
- "Show me CPU usage across all cores"
- "How much memory am I using?"
- "Is my system running hot?"
- "What processes are using the most GPU memory?"
Terminal User Interface (TUI)
IronMonitor includes a beautiful TUI for real-time monitoring with integrated AI agent:
# Build and run the TUI
# Or after installation (using either binary name)
TUI Features:
- ๐ Real-time graphs with 60-second history
- ๐จ Selectable color themes - Press
tto choose from 6 themes (Catppuccin Mocha/Latte, Glances, Nord, Dracula, Gruvbox Dark) - โจ๏ธ Keyboard navigation (โ/โ or 1-6 for tabs, Q to quit)
- ๐ Sparkline charts for trends
- ๐ Process selection - Use โ/โ arrows to navigate processes, Enter for detailed view
- ๐ค Integrated AI Agent - Press
ato ask questions about your system - ๐ฅ๏ธ 6 tabs: Overview, CPU, GPU, Memory, System, Agent
Keyboard Shortcuts:
| Key | Action |
|---|---|
q |
Quit |
Tab |
Cycle process sort mode |
โ/โ |
Select process |
Enter |
Open process detail view |
Esc |
Close overlay/detail view |
t / T |
Open theme picker |
PgUp/PgDn |
Page through processes |
Home/End |
Jump to first/last process |
r |
Reset scroll position |
Agent Tab:
- Natural language queries: "What's my GPU temperature?"
- Conversation history with timing
- Response caching for instant repeated queries
- Zero impact on monitoring performance
See AGENTS.md for driving the TUI from an agent, including reading frames without a terminal and scripting navigation.
Captured from a real run with ironmon tui --frame --tab Overview, using the same
headless renderer the test suite drives โ so it cannot drift from what the TUI
actually draws. Only the hostname is substituted.
โIronMonitor โ CPU:99% MEM:45% GPU:0 โ hostnameโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Overview โ Processes โ CPU โ Accelerators โ Memory โ System โ Peripherals โ Profiles โ Agent โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โCPUโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโCPU โ 99% โ 24 cores @ 4400 MHz [โโโโโโโโโโโโโโโโโฆ] โโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โMemoryโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโMEM โ 45% โ 42.6G/93.6G โ SWAP: 106.8G โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โNetworkโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโNET โ0B/s โ0B/s โ Total: โ34.9G โ55.5G โ Ethernet, vSwitch (Default Switch) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โCPU History (60s)โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโMemory History (60s)โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ โโโโ โ
โ โ โโโโ โ
โโโ โโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Tab Navigate 1-8 Jump q Quit t Theme โ OK CAREFUL WARNING CRITICAL โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Every other tab renders the same way โ pass --tab Processes, CPU,
Accelerators, Memory, System, Peripherals, Profiles, or Agent.
Graphical User Interface (GUI)
IronMonitor also includes a native desktop GUI built with egui for a modern graphical experience. It can also be read without a display via ironmon gui --frame, or driven by a script with ironmon gui --script:
# Build and run the GUI
# Or after installation
GUI Features:
- ๐ผ๏ธ Native desktop application (Windows, Linux, macOS)
- ๐ฅ๏ธ System page with hostname, OS and kernel, architecture, CPU and motherboard
details, BIOS/UEFI, Secure Boot, temperatures and drivers, plus a live summary
of OS uptime, CPU utilization, accelerator names, RAM/swap usage and process
count. Open it from the System tab, or inspect it headlessly with
ironmon gui --frame --tab system. - ๐จ 18 palettes, including Dark Monochrome, Dracula, One Dark Pro, Tokyo Night, Nord, Monokai and GitHub Dark, shared across tabs
- ๐ Real-time graphs and visualizations
- ๐ Auto-refreshing metrics
- ๐ฑ๏ธ Mouse-friendly interface with scrollable panels
- ๐ Historical data with trend charts
- ๐ค Background AI queries with tool progress and cancellation
- ๐ ๏ธ Tools page for bounded observation, process, connection, service, event and endpoint diagnostics
- Compact header, wrapping navigation and readable Profiles groups
Screenshots pending. This section previously linked six PNGs under
docs/images/that were never added, so every one rendered as a broken image here and on crates.io. Runironmon guito see it, or read a tab's text content without a display viaironmon gui --frame --tab Overview. The capture guidelines for contributing real screenshots are indocs/images/README.md.
Hardware Profile Inspector
IronMonitor v1.4 ships a unified inspector for vendor driver settings,
application profiles, and tunable hardware parameters โ the same surface
exposed by NVIDIA Profile Inspector, Intel XTU, AMD Ryzen Master, and
nvme-cli, but with one cross-platform CLI / GUI / TUI / MCP interface.
Subsystems covered: GPU (NVML, NVIDIA DRS scan, AMD sysfs, Intel i915/xe, Windows driver-class registry), CPU (cpufreq, intel_pstate, MSR PL1/PL2, Windows power schemes), NVMe (sysfs + NVMe Get-Features ioctl), Display (refresh / HDR / EDID), Memory (SMBIOS Type 17 + XMP 2.0/3.0 + AMD EXPO).
Apply layer: opt-in write handlers behind --confirm. Every attempt is
JSON-line audited. MCP agents additionally require IRONMON_ALLOW_AGENT_WRITES=1.
Current handlers: NVIDIA persistence mode (Linux), Linux cpufreq governor,
AMD power_dpm_force_performance_level, Intel gt_max_freq_mhz, Windows
active power scheme.
Prometheus metrics: ironmon_profile_deviations_count{risk},
ironmon_profile_settings_total{subsystem}, ironmon_profile_cache_hits_total,
and friends โ wired into the existing exporter.
See examples/profile_inspector.rs and
examples/active_profiles.rs for usage.
Examples
The repository includes comprehensive examples:
gpu_monitor.rs- Multi-vendor GPU monitoring with all metricsnvidia_monitor.rs- NVIDIA-specific features (NVML)amd_monitor.rs- AMD-specific features (sysfs/DRM)intel_monitor.rs- Intel-specific features (i915/xe)all_gpus.rs- Unified multi-vendor GPU examplecpu_monitor.rs- CPU metrics and per-core statsmemory_monitor.rs- Memory and swap usagedisk_monitor.rs- Disk I/O and SMART datamotherboard_monitor.rs- System information and sensorsprocess_monitor.rs- Process listing with GPU attributionnetwork_monitor.rs- Network interface statisticstui.rs- Interactive terminal UIaudio_monitor.rs- Audio device enumeration and volumebluetooth_monitor.rs- Bluetooth adapter and device discoverydisplay_monitor.rs- Display/monitor informationusb_monitor.rs- USB device enumerationagent_simple.rs- AI agent quick demoagent_demo.rs- AI agent interactive demo with model selection
Run any example with:
Platform Support
| Platform | CPU | Memory | Disk | GPU (NVIDIA) | GPU (AMD) | GPU (Intel) | GPU (Apple) | Network | Audio | Bluetooth | Display | USB |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Linux | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ |
| Windows | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ |
| macOS | ๐ง | ๐ง | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ |
โ Fully Supported | ๐ง Partial/In Progress | โ Not Supported
macOS CPU and memory are partial.
stats::IronMonitorreads CPU utilisation (per-core, including nice time, viahost_processor_info), memory, swap, uptime and board info on macOS. As on Linux, CPU percentages come from cumulative ticks and so are averages since boot rather than instantaneous rates.
IronMonitor::snapshot()still fails on macOS because it requires every reader, and GPU, power and temperature remain unimplemented there. UseIronMonitor::cpu(),IronMonitor::memory()andIronMonitor::uptime(), which read only what works. The table claimed full CPU and memory support through 2.1.2, when neither existed; that claim survived because the crate could not build on macOS at all, so nothing ever exercised it.macOS disk support covers enumeration, device info and health. Per-device I/O counters are not available:
iostatreports rates rather than the cumulative counters the API is built around, and there is no way to attribute its single combined throughput figure to reads versus writes.
GPU Backend Details
NVIDIA:
- Linux: Full NVML support via
libnvidia-ml.so - Windows: Full NVML support via
nvml.dll - Metrics: All metrics supported - utilization, memory, clocks, power, temperature, processes, throttling, ECC
- Devices: GeForce, Quadro, Tesla, Jetson (Nano, TX1/TX2, Xavier, Orin, Thor)
AMD:
- Linux: sysfs via
/sys/class/drm/card*/device/ - Windows: WMI performance counters (
Win32_PerfFormattedData_GPUPerformanceCounters) for utilization, memory, and temperature - Metrics: Utilization (GFX/compute), VRAM, clocks (SCLK/MCLK), temperature, power, fan speed
- Devices: RDNA 1/2/3, CDNA 1/2 (Radeon RX 5000+, Instinct MI series)
- Requirements: amdgpu driver (Linux), AMD display driver (Windows)
Intel:
- Linux: i915/xe drivers via
/sys/class/drm/card*/ - Windows: WMI performance counters for utilization, memory (shared + dedicated), and temperature
- Metrics: GT frequency, memory (discrete GPUs), temperature, power via hwmon
- Devices: Arc A-series, Iris Xe, UHD Graphics, Data Center GPU Max
- Requirements: i915 (legacy) or xe (modern) kernel driver (Linux), Intel graphics driver (Windows)
Apple:
- macOS:
powermetrics+system_profilerfor GPU detection and monitoring - Metrics: Utilization, frequency, power draw (via powermetrics plist output)
- Devices: Apple Silicon M1/M2/M3/M4 (Base, Pro, Max, Ultra) integrated GPUs
- Requirements: macOS with Apple Silicon; sudo for full powermetrics data
Architecture
ironmon/
โโโ core/ # Core metric structs (CPU, memory, power, etc.)
โโโ gpu/ # Multi-vendor GPU abstraction
โ โโโ mod.rs # Unified Device trait, GpuCollection
โ โโโ nvidia_new.rs # NVIDIA backend (NVML)
โ โโโ amd_rocm.rs # AMD backend (sysfs/DRM)
โ โโโ intel_levelzero.rs # Intel backend (i915/xe)
โโโ disk/ # Disk I/O and SMART monitoring
โโโ motherboard/ # System info, BIOS, sensors
โโโ silicon/ # Apple/Intel/AMD silicon-level monitoring
โโโ audio/ # Audio device enumeration
โโโ bluetooth/ # Bluetooth adapter/device monitoring
โโโ display/ # Connected display monitoring
โโโ usb/ # USB device enumeration
โโโ hwmon/ # Hardware monitor sensors
โโโ observability/ # AI-oriented observability API
โโโ ai_api/ # AI agent tools and ontology
โโโ process_monitor.rs # Process enumeration with GPU attribution
โโโ network_monitor.rs # Network interface statistics
โโโ tui/ # Terminal user interface (ratatui)
โโโ bin/main.rs # CLI/TUI entry point
โโโ platform/ # Platform-specific implementations
API Documentation
GPU Collection API
The GpuCollection provides a unified interface for all GPU vendors:
use ;
// Auto-detect all available GPUs
let collection = auto_detect?;
// Get count of detected GPUs
println!;
// Snapshot all GPUs at once
let snapshots = collection.snapshot_all?;
// Access individual devices
for device in collection.gpus
Process Monitoring
The ProcessMonitor correlates system processes with GPU usage:
use ProcessMonitor;
use GpuCollection;
let gpus = auto_detect?;
let mut monitor = with_gpus?;
// Get all processes
let processes = monitor.processes?;
// Get top GPU consumers
let gpu_procs = monitor.processes_by_gpu_memory?;
// Get top CPU consumers
let cpu_procs = monitor.processes_by_cpu?;
// Get only GPU processes
let gpu_only = monitor.gpu_processes?;
Network Monitor API
The NetworkMonitor tracks network interface statistics:
use NetworkMonitor;
let mut monitor = new?;
// Get all interfaces
let interfaces = monitor.interfaces?;
// Get only active interfaces
let active = monitor.active_interfaces?;
// Get specific interface
if let Some = monitor.interface_by_name?
Full API documentation:
Building from Source
Prerequisites
Linux:
# Ubuntu/Debian
# Fedora
# Arch
# For NVIDIA support, install CUDA toolkit or driver (provides libnvidia-ml.so)
Windows:
# Install Visual Studio Build Tools (2019 or later)
# For NVIDIA support, install CUDA toolkit or NVIDIA driver (provides nvml.dll)
macOS:
# Install Xcode command line tools
Compilation
# Clone the repository
# Development build
# Release build (optimized)
# Run tests
# Run specific example
Contributing
Contributions are welcome! Areas that need help:
- macOS CPU and memory readers โ the largest gap. ironmon builds and passes its
suite on macOS but reads neither: there is no
platform/macos.rs, andstats::IronMonitor's ten platform functions returnUnsupportedPlatform. This needs sysctl and IOKit work verified on real hardware. - Apple GPU enhancements: Apple Silicon GPU auto-detection is integrated via
GpuCollection::auto_detect(); could add Metal Performance Shaders for richer metrics - macOS Process I/O: I/O read/write bytes and handle counts on macOS
- CPU% refinements: CPU% now uses delta-based sampling (matching Task Manager/top behavior); further improvements could include per-core attribution
- Documentation: More examples, tutorials, API documentation
- Testing: Multi-GPU setups, edge cases, platform-specific bugs
See CONTRIBUTING.md for guidelines.
Development Workflow
# Format code
# Run clippy
# Run tests
# Build documentation
# Run examples
License
This project is dual-licensed:
- Open Source: GNU Affero General Public License v3.0 (AGPL-3.0) โ free for open-source use with copyleft obligations
- Commercial: A proprietary license is available for closed-source, SaaS, or embedded use without AGPL requirements
Contributors must agree to the Contributor License Agreement to enable dual licensing.
See LICENSE-COMMERCIAL.md for commercial licensing details and contact information.
Acknowledgments
IronMonitor builds upon and is inspired by:
- jetson-stats by Raffaello Bonghi - Comprehensive monitoring for NVIDIA Jetson devices
- nvtop - GPU monitoring TUI for Linux
- radeontop - AMD GPU monitoring
- intel_gpu_top - Intel GPU monitoring
Special thanks to the Rust community and the maintainers of the following crates:
- ratatui - Terminal UI framework
- sysinfo - System information
- nvml-wrapper - NVIDIA NVML bindings
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs.rs/ironmon
Made with ๐ฆพ by NERVOSYS