Solvik/netbox-agent: hardware inventory pushed into Netbox from the host itself

The gap between a running server and a Netbox record

Netbox is a database, and something has to fill it. The README states the project's aim plainly: create hardware automatically in Netbox based on standard tools such as dmidecode, lldpd and parsing /sys/. The target reader is whoever currently types serial numbers, NIC MAC addresses and RAID card details into Netbox by hand, or maintains a separate CMDB export that drifts from reality the week after it is generated. The agent is installed on the server it describes. It reads the machine locally, then talks to the Netbox API through pynetbox. That direction of travel matters: the agent does not scan a subnet, it does not need SNMP credentials for every switch, and it does not require the Netbox instance to reach into the estate. It requires the estate to reach Netbox. A server that has been racked, cabled and powered will describe itself the first time the agent runs. The README's example output shows a blade being created alongside its chassis, NICs created by MAC address, an IPMI interface picked up, and IPv4 and IPv6 addresses attached to the right interfaces. That is the whole proposition: one command turns a physical host into Netbox objects.

What the agent reads and what it writes back

The collection layer is a set of host tools rather than a custom probe. dmidecode supplies chassis and blade serials, lldpd supplies neighbour information used for cabling, /sys/ is parsed for interface data, and ipmitool, ethtool and lshw cover the rest. Inventory reporting additionally depends on hpassacli, storcli and omreport, which are vendor tools and therefore only present on hosts from the matching vendors. The write layer maps that data onto Netbox object types: Device (with the parent/child relationship for chassis and blades), Interface (physical, bonding and VLAN), IP addresses, VLANs, Inventory Items for CPU, GPU, RAM, RAID cards and physical disks behind RAID cards, and PSUs with power consumption figures taken from vendor tools. Cabling is derived from LLDP answers, so a server's interface can be linked to the switch interface it is actually plugged into. Two configuration-driven drivers, cmd and file, handle datacenter and rack location: the agent runs a shell command or reads a file, applies a regex, and uses the captured group as the location. The README's own example pipes /etc/qualification through tr and matches datacenter: (?P<datacenter>[A-Za-z0-9]+). That design keeps site-specific logic out of the code. It also means the quality of your location data depends entirely on the regex you write, and a regex that matches nothing fails quietly rather than loudly.

Running it: one binary, four configuration sources

Installation is a single pip command: pip3 install netbox-agent. The agent takes its configuration from a file or from environment variables, and the README gives the precedence order explicitly: command line arguments (which may include a config file) override environment variables, which override the default config file, which overrides built-in defaults. The minimal configuration block needs a Netbox URL and token, with ssl_verify and ssl_ca_certs_file available if you terminate TLS with a private CA. Network behaviour is governed by ignore_interfaces and ignore_ips, both regexes, and by lldp: true to turn on auto-cabling. The README's default ignore_interfaces value is (dummy.*|docker.*), which tells you the agent will happily inventory container bridges and loopback addresses if you do not narrow it. Registration is netbox_agent -c /etc/netbox_agent.yaml --register. Partial runs are supported and are the more useful mode in day-to-day operation: --update-network after adding an address, --update-inventory to refresh disks and cards, plus separate flags for location and PSUs. Two further flags change object shape rather than scope: --expansion-as-device registers a GPU or drive expansion bay as its own device instead of folding its hardware into the blade, and --process-virtual-drives writes extended disk attributes as Netbox custom fields. Both have config-file equivalents, expansion_as_device and process_virtual_drives.

Blades, expansion bays and the custom field prerequisite

Blade handling is where the agent stops being a generic collector. Each vendor class implements an is_blade method, which drives Device creation through Netbox's parent/child feature, and a get_blade_slot method that returns the name of the Device Bay. The README admits a real limitation here: certain vendors do not report the blade slot in dmidecode, so the slot_location regex in the configuration file exists as a workaround. If your hardware is in that category and you do not write the regex, slot placement is guesswork. The expansion bay feature has a harder prerequisite. Processing virtual drives writes attributes such as mount point, physical disk identifier, logical drive RAID type and size as custom_fields on DCIM > inventory item, and the README is explicit that these fields must be created in Netbox beforehand as Text fields. This is not an optional nicety. Enabling process_virtual_drives without the fields in place gives you a feature that cannot store what it collected. The same ordering constraint applies to the device-level tags and custom_fields settings shown in the configuration sample, which are comma-delimited lists and field1=value1 pairs respectively.

Where this approach breaks down

The agent is push-based and host-installed, and that single design choice excludes whole categories of environment. Appliances, switches, storage arrays and hypervisor hosts you cannot install Python packages on are out of scope. So are servers where you will not add dmidecode, lldpd, ipmitool, ethtool and lshw, since the README lists them as requirements rather than optional extras. The vendor inventory tools narrow it further: hpassacli, storcli and omreport each come from a specific hardware vendor, so a mixed fleet will get inventory data from some hosts and not others. There is a second failure mode around identity. The agent creates objects keyed on what the host reports, and the README's example output shows interfaces being created because a MAC address was not found. A reimaged host, a replaced NIC or a changed serial can therefore produce a new object next to the stale one rather than updating it. The documentation does not describe a reconciliation or cleanup pass, so pruning duplicates is left to the operator. Finally, the project's build badge points at travis-ci.com, which has been retired for public repositories. That is a signal about how much continuous integration still runs, not a statement about code quality, but it is worth knowing before you depend on the test suite.

How it differs from Netbox's own discovery tooling

Netbox maintains its own discovery mechanism, and the comparison is instructive because the two solve the same problem from opposite ends. Netbox's discovery scans configured network ranges and probes devices over the network, which suits switches, routers and appliances that cannot run code. netbox-agent inverts that: it runs on the host, so it can read dmidecode for chassis and blade serials, enumerate RAID cards through storcli, and report PSU power consumption from vendor tools, none of which are reachable over a network probe. The trade is coverage against depth. A network scan reaches everything with an IP address and gets comparatively little detail. An installed agent reaches only hosts you control and gets inventory items, GPU expansions, blade slot positions and cabling from LLDP. The two are not mutually exclusive, and a shop with both servers and network gear will likely run them side by side and accept that the same device may be described by two sources. The agent's other distinguishing trait is its driver model for datacenter and rack location, which lets you encode site conventions in a regex instead of maintaining a mapping table.

Maintenance, licensing and what the release history shows

The project is licensed Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved and any modified files carry prominent change notices. That is the general shape of the licence, not legal advice; read the LICENSE file and the NOTICE requirements before redistributing a modified agent inside a product. On cadence, the release history shows three tagged releases: v1.0.0 in October 2024, v1.1.0 in January 2025, and 1.2.0 in January 2026, with the repository's last push dated September 2026. That is a slow but non-zero rhythm, roughly one release per year, and it has a practical consequence: the agent tracks Netbox's API, and Netbox ships on its own schedule. The README sets a floor of Netbox 3.7 and Python 3.8. Upgrading Netbox past that floor is the moment to re-read the agent's release notes, because a pynetbox or API change can break registration in ways that only appear when the agent runs. Budget for that coupling rather than assuming the agent is inert once installed.

Editorial conclusion

Adopt netbox-agent if you run Netbox 3.7 or later, your servers are reachable by the agent and you can install dmidecode, lldpd, ipmitool, ethtool and lshw on them. Do not adopt it if you need a pull-based collector that inventories hosts you cannot install packages on, or if you cannot create the custom fields its virtual drive feature depends on. Before rolling it out, run netbox_agent -c /etc/netbox_agent.yaml --register against one non-production host and check the resulting Device, Interface and Inventory Item records against the host's actual hardware.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. Solvik/netbox-agent on GitHub