doca-hardware-safety

Enforces pre-flight inventory, out-of-band access, and rollback discipline for DPU and NIC hardware changes.

3.2k|370|Updated Feb 25, 2026
One-click install
npx skills add https://github.com/NVIDIA/skills --skill doca-hardware-safety
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: doca-hardware-safety
Source: https://github.com/NVIDIA/skills/tree/main/skills/doca-hardware-safety
Command: npx skills add https://github.com/NVIDIA/skills --skill doca-hardware-safety

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Applying hardware-touching changes to live NVIDIA BlueField DPU and ConnectX NIC systems — firmware burns, BFB reflashes, mode flips, mlxconfig writes, kernel boot-parameter changes — can brick devices, drop management links, or leave systems unrecoverable when done without a captured baseline, out-of-band access, or a tested rollback path.

Core Features & Use Cases

  • Change-application discipline: Walks operators through pre-flight inventory, out-of-band reachability, maintenance windows, apply/verify gates, and rollback ladders for every hardware-touching change class.
  • Refuse-and-escalate rules: Hard-refuses changes lacking a documented rollback, out-of-band path for link-breaking changes, a maintenance window, or replica-first validation.
  • Failure-mode prevention: Addresses bricked links, runaway firmware burns, silent mlxconfig mode changes (cold power cycle required), and discovered-during-failure rollbacks.
  • Use Case: Before flipping a BlueField from NIC to DPU mode over SSH, the skill requires confirming an out-of-band console, capturing the PCIe topology and firmware baseline, rehearsing the change and rollback on a replica, and framing a maintenance window.

Quick Start

Ask your agent to help you safely apply an mlxconfig firmware parameter change or BlueField BFB reflash on a live system, and it will load this skill's change-application discipline before recommending any command.

Frequently Asked Questions about doca-hardware-safety

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely apply an mlxconfig change on a BlueField DPU?

Capture the pre-flight inventory (PCIe topology, firmware level, config snapshot), confirm out-of-band access, frame a maintenance window, then apply the write and perform a cold power cycle. Warm reboots do not commit firmware-stored mlxconfig configuration.

What should I capture before a BlueField BFB reflash?

Capture the PCIe topology, link state, running firmware level, current BFB version, mlxconfig configuration snapshot, and host-side environment snapshot. This baseline is required for any rollback, since the reflash removes every hosted service container on the BlueField.

Does this skill work without a DOCA installation?

Reading the skill's guidance requires no DOCA install, but its validation steps require a live DOCA install at /opt/mellanox/doca with a BlueField DPU or ConnectX NIC. Link-breaking changes additionally require out-of-band console reachability via BMC, RShim, or an operator-managed console.

Why does the skill refuse some hardware changes?

It refuses changes lacking a documented rollback path, link-breaking changes without out-of-band access, changes outside a time-boxed maintenance window, and production changes not rehearsed on a representative replica. In those cases it escalates to change control or vendor support instead of guessing.

When should I use doca-debug instead of doca-hardware-safety?

Use doca-debug for program-side debugging that does not touch hardware state, such as DOCA_ERROR interpretation or lifecycle issues. doca-hardware-safety owns the change-application discipline and hands off to doca-debug once rollback has restored a known-good hardware state.