doca-bf4-deployment — skill for Claude Code: day-1 BlueField-4
doca-bf4-deployment — a skill for BlueField-4 DPU day-1 deployment via BMC: ISO installation, PLDM firmware update, Grace Ubuntu provisioning. Each mutating step requires explicit confirmation and is governed by rollback policy.
Apache-2.0 155 installs ★ 4,106 updated 2026-10-23
npx skills add NVIDIA/skills --skill doca-bf4-deployment -a claude-codeWhat doca-bf4-deployment does
This skill guides day-1 bring-up of BlueField-4: deploying the BlueField/DOCA bundle ISO to the DPU (Grace, the Arm complex) over UEFI HTTP Boot, PXE, or Redfish Virtual Media; updating platform firmware through Redfish UpdateService and pldmtool; preparing Grace Ubuntu with optional cloud-init. All irreversible operations—PLDM firmware burns, ISO reflashes, power cycles, BMC factory resets—route through doca-hardware-safety with pre-flight inventory checks, maintenance window confirmation, and rollback validation.
The skill targets BlueField-4 only; BlueField-3 bring-up goes to doca-bf3-deployment. Developers engage it for day-1 BlueField-4 bring-up, install-method selection, PLDM Task monitoring, image activation, state verification, and first smoke tests. Each step requires the user's explicit consent for that specific action; chained destructive operations and speculative side effects are prohibited.
Application launch and library APIs route to other skills. The skill does not redefine doca-hardware-safety policy and does not cover BlueField BSP, RShim, TMFIFO, or BMC software (those are externally productized).
What it helps with
- deploy BlueField/DOCA bundle ISO to DPU via BMC
- update PLDM firmware and activate images through Redfish
- provision Grace Ubuntu with cloud-init for day-1
- verify target firmware and OS versions match release notes
- rollback if a hardware operation corrupts DPU state
Example prompts for the agent
- Help me bring up BlueField-4 from bare metal using the BMC—which install method should I pick for the ISO?
- PLDM firmware update completed but NIC firmware did not advance—how do I diagnose this?
- Prep BlueField-4: check versions, confirm maintenance window, validate rollback plan before PLDM burn
How to install doca-bf4-deployment
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf4-deployment -a claude-code2Manually: put the files in place
~/.claude/skills/doca-bf4-deployment/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/doca-bf4-deployment/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf4-deployment -a codex2Manually: put the files in place
.agents/skills/doca-bf4-deployment/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf4-deployment -a cursor2Manually: put the files in place
.cursor/skills/doca-bf4-deployment/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install NVIDIA/skills skills/doca-bf4-deployment2Manually: put the files in place
.github/skills/doca-bf4-deployment/SKILL.md1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf4-deployment -a gemini-cli2Platform CLI
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-bf4-deploymentManually: put the files in place
.devin/skills/doca-bf4-deployment/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf4-deployment -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about doca-bf4-deployment
How do I install doca-bf4-deployment in Claude Code?
Run npx skills add NVIDIA/skills --skill doca-bf4-deployment -a claude-code, then open ~/.claude/skills/doca-bf4-deployment/SKILL.md. The skill requires a BlueField-4 with out-of-band-reachable BMC and an HTTP/HTTPS server to host the bundle ISO.
What does doca-bf4-deployment do?
The skill teaches day-1 BlueField-4 bring-up via BMC: OS and firmware installation, choice among UEFI HTTP Boot, PXE, and Redfish Virtual Media, PLDM firmware update monitoring, version verification. All mutating steps require explicit confirmation and rollback validation.
Does this skill work with BlueField-3?
No, it is BlueField-4 only. For BlueField-3, use the doca-bf3-deployment skill.
Source text
SKILL.md · Apache-2.0
---
license: Apache-2.0
name: doca-bf4-deployment
description: >
WARNING: guides IRREVERSIBLE BlueField-4 hardware operations (PLDM
firmware burns, ISO reflashes, power cycles, BMC factory resets); every
mutating step is governed by doca-hardware-safety (window, rollback).
BlueField-4 only: BlueField-3 bring-up is doca-bf3-deployment. Use this
skill for BlueField-4 (BF4) day-1 platform
bring-up from the BMC: installing the BlueField/DOCA bundle ISO onto
the DPU (Grace, the Arm complex) over UEFI HTTP Boot, PXE, or Redfish
Virtual Media; the PLDM platform-firmware update via the Redfish
UpdateService and pldmtool; and a Grace
Ubuntu image with optional cloud-init. Trigger on BlueField-4/BF4
bring-up phrasings even without "BF4": {bring up my new BlueField-4},
{the BlueField ISO will not boot over HTTP from the BMC}, {attach BF4
virtual media via Redfish}, {BF4 firmware Task stuck at Running}, {prepare a BlueField-4 host: platform
support, version alignment, safest first smoke test}. Route
application launch and library APIs to other skills.
metadata:
author: NVIDIA <[email protected]>
kind: library
doca_version: "3.5"
tags:
- doca
- bluefield-4
- deployment
compatibility: >
No DOCA install is required to read this skill; it teaches the
documented BlueField-4 BMC-driven bring-up flows (UEFI HTTP Boot,
PXE, Redfish Virtual Media, PLDM firmware update). Executing the
steps requires a BlueField-4 with an out-of-band-reachable BMC, a
host or HTTP/HTTPS server to host the bundle ISO, and the target
versions from the public BlueField/DOCA release notes.
The validation steps require a live DOCA install.
---
# DOCA BlueField-4 (BF4) deployment
## Examples
- **"I have a BlueField-4 and a BMC — how do I bring Grace up?"** —
BMC-driven day-1, not the BF3 RShim/BFB path. Do not invent
credentials or skip media detach.
- **"PLDM update finished but the NIC firmware did not move."** —
treat it as a firmware-Task / activation failure, not a second
burn by default.
**BlueField-3 or any other generation is not this skill.** Name
`doca-bf3-deployment` and stop; do not read further or run commands.
## Preparing a BlueField-4 host (answer from here)
1. **Platform:** confirm it is BlueField-4 and that the BMC is reachable
out of band; compare
the Redfish firmware inventory with the release notes' targets.
2. **Version alignment:** run the `doca-version` four-source chain on the
host. Fixing any mismatch changes hardware state and follows
`doca-hardware-safety`.
3. **Safest first smoke test:** read-only `doca_caps --list-devs`, then one
shipped sample per `doca-bare-metal-deployment`. No firmware, mode or
reset change before that is green.
4. **Say it in the answer:** every mutating step (PLDM firmware burn, ISO
reflash, power cycle, BMC reset) is routed through
`doca-hardware-safety`: pre-flight inventory, out-of-band access,
maintenance window, rollback, then apply and verify.
## Instructions
Follow Loading order below. Open the tasks companion for BMC bring-up
and recover. Open the capabilities companion for the three install
methods and the BF4 safety overlay. Do not open every companion file.
> ⚠️ **WARNING — irreversible hardware operations.** This skill guides
> operators through potentially destructive, irreversible BlueField-4
> hardware operations: PLDM firmware burns, ISO reflashes, power
> cycles, and BMC factory resets. These can brick firmware, corrupt
> boot media, or cause production outages. Do **not** proceed without a
> maintenance window and a tested rollback plan. Every mutating step is
> governed by
> `doca-hardware-safety/SKILL.md`, which
> MUST be loaded alongside this skill before any destructive action.
>
> Before executing any mutating step — PLDM firmware burn, ISO reflash,
> power cycle, or BMC factory reset — the agent MUST show the exact
> command and its blast radius (which device, what becomes unavailable,
> whether it is reversible) and obtain the user's explicit confirmation
> for that specific action. Never chain destructive steps or run them
> speculatively as a side effect of another task.
**Where to start:** This skill is the bundle's deliberate in-bundle
home for **day-1 platform bring-up of a BlueField-4 DPU via the
BMC** — getting a powered-but-bare BF4 to "Grace OS installed,
firmware at the target level, ready to deploy a workload." It is the
upstream of the two application-deployment skills
(`doca-container-deployment/SKILL.md`
and
`doca-bare-metal-deployment/SKILL.md`):
those skills assume a working BlueField; this skill is how the
BlueField-4 GETS to working. If the user has a fresh BF4 and wants to
install the OS or update firmware, open the tasks companion and
start at `## configure`. If the question is
*what bring-up methods even exist and what is the contract for each*,
start at the capabilities companion.
**How to use this skill.** Read this file, then search the companion file
for the `## <name>` heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in `doca-public-knowledge-map`. Give
environment checks as commands for the user's DOCA host. For out-of-scope
requests, name the skill that owns them and stop.
> **Scope note — BF4 day-1 is in scope.** The bundle's
> `AGENTS.md ## Non-goals` (bundle `AGENTS.md#non-goals-questions-the-agent-should-recognize-and-refuse-politely`)
> item 7 lists the BlueField BSP / BFB / RShim / TMFIFO layer and the
> BlueField BMC software as externally-productized. **BlueField-4
> day-1 bring-up via the BMC is in scope for this skill** because day-1 has no other home in the bundle. The
> carve-out is narrow: this skill teaches the documented BMC-driven
> install and firmware-update FLOWS (the CLASS), routing every
> *mutating* step through
> `doca-hardware-safety/SKILL.md` for the
> change-application meta-policy. It does NOT redefine that
> meta-policy, and it does NOT cover BF3 (route to
> `doca-bf3-deployment`), application launch, or library APIs.
## When to load this skill
Load this skill when the user is doing **hands-on day-1 bring-up of a
BlueField-4 via the BMC**, or asking a cross-cutting BF4-bring-up
question that is not specific to a later application-deployment step.
Concretely:
- Installing the BlueField/DOCA bundle ISO onto the DPU (Grace) for
the first time, and choosing between the install methods — UEFI
HTTP Boot, PXE Boot, Redfish Virtual Media, or the DOCA Management
Service install path.
- Running the PLDM firmware-update flow across the BMC, NIC firmware
and the other platform components the PLDM package lists: pushing the `.fwpkg` bundle through the
Redfish UpdateService multipart endpoint, monitoring the returned
Task, verifying pending images with `pldmtool`, and activating with
a power cycle.
- Installing a Grace Ubuntu image (with optional cloud-init via a
CIDATA-labelled config ISO) through Redfish Virtual Media, with
either local hosting on the BMC eMMC or remote hosting on an
HTTPS server.
- Reaching the DPU's OOB serial console (BMC SSH plus
`obmc-console-client`) to watch the installer or UEFI menus.
- Diagnosing a bring-up that is misbehaving — the ISO will not boot,
virtual media will not attach, a firmware Task hangs or reports an
Exception, a pending image never activates, cloud-init is ignored,
or the DPU is stuck in a boot loop because media was never detached.
- Cross-cutting questions: *"HTTP Boot or Redfish Virtual Media — which
do I use, and when do I actually need PXE?"*, *"how do I know the
firmware update actually took effect?"*, *"the ISO landed but the
NIC firmware update sub-step seems to have failed — what now?"*.
Do **not** load this skill for BF3 bring-up (route to
`doca-bf3-deployment`); for running an application on an
already-working BlueField (route to
`doca-container-deployment/SKILL.md`
or
`doca-bare-metal-deployment/SKILL.md`);
for env preparation on the installed Grace OS such as hugepages /
pkg-config / devlink (use `doca-setup/SKILL.md`); for
the cross-cutting hardware-change meta-policy (route to
`doca-hardware-safety/SKILL.md`); or for
fleet-scale orchestrated provisioning (route via
`doca-public-knowledge-map/SKILL.md`).
## What this skill provides
This is a **thin loader**. Substantive material lives in two
companion files:
- the capabilities companion — the BF4 day-1 bring-up contract: the three OS
install methods (UEFI HTTP Boot, PXE Boot, Redfish Virtual Media)
and the Grace-Ubuntu-plus-cloud-init Virtual Media path; the PLDM
firmware-update surface across the platform firmware components;
the version-compatibility overlay on
`doca-version/SKILL.md` (the install and firmware
targets come from the public release notes, never from memory); the
bring-up error taxonomy (boot-source -> virtual-media-attach ->
firmware-Task -> activation -> cloud-init -> boot-loop); the
observability surface (the OOB console, the Redfish Task resource,
the Redfish FirmwareInventory, `pldmtool` GetFwParams, and the
installed-build check `cat /etc/mlnx-release`); and the safety
policy (an overlay on
`doca-hardware-safety/SKILL.md`: every
PLDM burn / ISO reflash / power cycle / BMC factory reset is a
MUTATING hardware op; never print a real password; always detach
virtual media to avoid boot loops; only public hosts for any
NVIDIA URL).
- the tasks companion — step-by-step workflows for the in-scope bring-up verbs:
`configure`, `build` (routing stub), `modify` (routing stub), `run`
(the three install methods plus the PLDM firmware-update flow plus
the Grace-Ubuntu cloud-init path, as `###` sub-anchors), `test`
(the post-install / post-update verification sweep), `debug` (the
layered bring-up diagnosis), and the `Deferred task verbs` block
routing BF3 / application-launch / library-API / env-prep /
hardware-meta-policy / fleet questions out to their owning skills.
The skill assumes a BlueField-4 target where:
- the BMC is reachable out-of-band and the operator has BMC
credentials ({bmc-user} / {bmc-password}) they supply — never
invented here,
- the bundle ISO (and any Grace Ubuntu image / cloud-init config ISO)
is downloaded from the public NVIDIA download surface and hosted at
{iso-uri},
- the operator has read the target firmware and OS versions from the
public BlueField/DOCA release notes.
It does not cover installing DOCA tooling on the host — that path goes
through `doca-setup/SKILL.md` — and it does not cover
running a workload once Grace is up — those paths go through the two
application-deployment skills.
## Loading order
1. Read this skill first to confirm the user's question is in
scope (BF4 day-1 bring-up via the BMC; NOT BF3, NOT application
launch, NOT a library-API question, NOT the hardware-change
meta-policy itself).
2. **For the bring-up contract (the three install methods, the
Grace-Ubuntu cloud-init path, the PLDM firmware-update surface, the
version overlay, the bring-up error taxonomy, the observability
surface, and the BF4 safety overlay), see
the capabilities companion.**
3. **For step-by-step workflows — `configure`, `build` (routing
stub), `modify` (routing stub), `run` (with the three install
methods, the PLDM flow, and the Grace-Ubuntu cloud-init path as
`###` sub-anchors), `test`, `debug`, plus the `Deferred task verbs`
block — see the tasks companion.**
4. **Load
`doca-hardware-safety/SKILL.md`
ALONGSIDE** whenever the question reaches a mutating step (PLDM
firmware burn, ISO reflash, power cycle, BMC factory reset).
## Related skills
- `doca-bf3-deployment/SKILL.md` — BF3 RShim/BFB day-1.
- `doca-hardware-safety/SKILL.md` — PLDM, reflash, power cycle.
- `doca-bare-metal-deployment/SKILL.md` — launch after Grace is up.
- `doca-container-deployment/SKILL.md` — service container after Grace is up.
- `doca-setup/SKILL.md` — env prep on the installed Grace OS.
- `doca-version/SKILL.md` — four-way version match.
- `doca-public-knowledge-map/SKILL.md` — public docs and release notes.
© NVIDIA · Apache-2.0 · NVIDIA/skills