Hardware Automation
Hardware Report: Open-Source Inventory Evidence for Real Infrastructure
How the open-source hardware_report Rust crate turns Linux and macOS host facts into structured TOML/JSON evidence for observability, cluster acceptance testing, CMDB population, and bare-metal lifecycle automation.
Context
Hardware Report is the open-source discovery layer that pairs with in-band hardware lifecycle automation. It does not mutate a host or try to become a control plane. It inspects the machine, normalizes what it can see, and emits structured evidence that other systems can trust, compare, publish, or archive.
The crate is published as hardware_report on crates.io and points to the Codeberg source. It is written in Rust and built around hexagonal architecture: the domain model and collection service stay independent, while Linux, macOS, command execution, file output, and HTTP publishing live behind ports and adapters.
This matters for AI NeoCloud and bare-metal acceptance workflows because expensive infrastructure mistakes often start with bad inventory. You need to know CPU topology, NUMA layout, memory, storage, GPUs, NICs, firmware, chassis identity, BMC/IPMI data, and network facts before schedulers, VM runtimes, or Kubernetes can make safe placement decisions.
In the larger agent model, Hardware Report supplies a concrete evidence primitive. A stateful bare-metal agent can invoke it locally, keep the TOML/JSON report while offline, and sync the result back to a control plane when connectivity returns. That makes observed hardware state part of distributed reconciliation instead of a screenshot or one-off command transcript.
01
What the Crate Collects
The public README and source show discovery for CPU model, sockets, cores, threads, NUMA topology, cache hierarchy, memory capacity and configuration, storage devices, NVIDIA GPU information, network interfaces, BIOS, BMC/IPMI, chassis serial, and motherboard details.
On Linux, the provider prefers kernel-facing sources such as sysfs and procfs, then uses command output from tools like lscpu, dmidecode, free, lsblk, ip, hostname, df, and nvidia-smi where appropriate. The source also keeps a fallback posture: partial hardware data is more useful than failing the whole acceptance flow unnecessarily.
02
Architecture Shape
The implementation follows ports-and-adapters architecture. Primary ports expose the reporting service to the CLI and library consumers. Secondary ports abstract system information, command execution, configuration, file storage, and HTTP publishing. The domain service coordinates collection and returns a HardwareReport aggregate.
The service collects major hardware groups concurrently with tokio::join, then builds a SystemSummary with CPU topology, total memory, storage totals, filesystem data, BIOS, chassis, motherboard, GPU count, NIC count, NUMA topology, and system identity. Output can be saved as TOML/JSON or posted as JSON with labels and an optional system identifier.
03
Why It Belongs With the Baremetal Agent API
Hardware Report is the read-side evidence tool. The Baremetal Agent API is the stateful automation layer around it. Together they let a Linux host report what it is, preserve that report while disconnected, and later reconcile it with desired state, validation profiles, or cluster acceptance policy.
Because the crate can be built with Nix or installed through Cargo, it fits the same distro-agnostic Linux story as the agent. The target does not have to be NixOS: Debian, Ubuntu, CentOS, Red Hat, NixOS, and other Linux systems can be inspected, reported, and then used as inputs to in-band lifecycle decisions.
Architecture Patterns
Public Diagrams for the Operating Model
Hardware Report Hexagonal Architecture
The crate keeps the hardware reporting domain separate from CLI, OS adapters, command execution, file output, and HTTP publishing.
CLI / Library
The hardware_report binary and create_service API call the primary reporting port.
Primary Port
HardwareReportingService exposes generate_report, publish_report, dependency validation, and privilege checks.
Domain Service
HardwareCollectionService coordinates collection, summary generation, and publishing without knowing OS details.
Entities
HardwareReport, SystemSummary, CpuInfo, MemoryInfo, StorageInfo, GpuInfo, NetworkInfo, BIOS, chassis, and motherboard data form the schema.
Secondary Ports
SystemInfoProvider, CommandExecutor, ConfigurationProvider, DataPublisher, and FileRepository isolate external dependencies.
Adapters
Linux/macOS providers, Unix commands, HTTP publisher, and file repository implement the external side.
Collection and Publication Flow
A run turns host-local discovery into portable evidence for files, APIs, CMDBs, acceptance gates, or agent sync.
Validate
Check dependencies and privileges before relying on privileged host discovery paths.
Collect Hardware
CPU, memory, storage, GPU, and network data are collected concurrently.
Collect Metadata
System identity, BIOS, chassis, motherboard, NUMA topology, and filesystems are gathered.
Summarize
CPU topology, memory config, storage totals, GPU count, NIC count, and machine identity become SystemSummary.
Serialize
The HardwareReport aggregate is emitted as TOML or JSON for review and automation.
Publish
Optional HTTP publishing sends JSON with labels, bearer auth, and an optional system identifier.
Agent Integration Pattern
Hardware Report provides the evidence primitive a stateful bare-metal agent can use before kubelet, VM runtimes, or schedulers take ownership.
Linux Host
Debian, Ubuntu, CentOS, Red Hat, NixOS, or another Linux system runs the tool locally.
Hardware Report
The crate inspects hardware and writes a structured TOML/JSON report without mutating the host.
Local Store
A stateful agent can persist reports, checkpoints, and labels while offline.
Sync
When connectivity returns, the agent syncs evidence over its authenticated control-plane path.
Acceptance Gate
Reports feed placement, lifecycle policy, CMDB updates, cluster acceptance, and re-image decisions.
What to Understand
- Hardware Report is open-source and published as hardware_report v0.1.7 on crates.io, with source and homepage pointing to Codeberg.
- The crate is evidence-oriented: it collects and structures facts rather than mutating the host or pretending to be a long-running control plane.
- Its hexagonal architecture keeps domain entities and report generation independent from Linux/macOS providers, command execution, file output, and HTTP publishing.
- Linux collection combines sysfs, procfs, standard command output, and fallbacks so infrastructure teams get useful partial evidence even when some tools or privileges are missing.
- The output is useful upstream of kubelet, VM runtimes, Slurm, CMDBs, or acceptance gates because it captures what the machine actually is before higher layers trust it.
Common Failure Modes
- Treating a generated inventory report as a control loop instead of feeding it into a stateful reconciliation system.
- Assuming every field is present on every platform; real hardware discovery needs explicit handling for missing commands, permissions, drivers, and virtual devices.
- Publishing reports without stable system identity, labels, or acceptance context, making it hard to correlate evidence with lifecycle decisions.
- Using the report as a static spreadsheet replacement instead of comparing it against desired profiles, placement rules, or hardware acceptance policy.
What Good Looks Like
- A host can produce a structured TOML/JSON hardware report with CPU, memory, storage, GPU, NIC, firmware, chassis, motherboard, NUMA, and identity evidence.
- Reports can be saved locally for disconnected operation and later synced by a stateful bare-metal agent.
- Acceptance workflows can compare observed hardware against intended profiles before kubelet joins, VM placement, ML workloads, or accelerated compute pipelines run.
- The crate remains usable as both a CLI and a library, so operators can run it manually while automation can embed it behind a Baremetal Agent API.