doca-bf3-deployment — Claude Code skill: BlueField-3 via RShim
doca-bf3-deployment is a skill for day-1 BlueField-3 provisioning over classic RShim/BFB, handling BFB image push, TMFIFO setup, DPU mode selection, and recovery.
Apache-2.0 159 installs ★ 4,106 updated 2026-10-23
npx skills add NVIDIA/skills --skill doca-bf3-deployment -a claude-codeWhat doca-bf3-deployment does
This skill covers the full day-1 cycle for BlueField-3: from a card in the slot to a healthy Arm OS, TMFIFO up, and ready to run workloads. It handles the RShim/BFB provisioning path (not BMC-Redfish, which is for BF4), host-side BFB push with bfb-install, host-to-DPU TMFIFO channel management via the 192.168.100.x convention on tmfifo_net0, RShim daemon and console state, DPU mode selection (DPU/embedded-function vs separated-host/NIC) through mlxconfig, recovery when a DPU does not return after push, and verification via cat /etc/mlnx-release with four-way version checks.
Requires a physical BlueField-3, RShim access over PCIe or USB, a DOCA-Host install on the host, and a BFB image from the public DOCA Downloads page. All destructive operations—BFB reflash, mlxconfig set, mode flip, firmware burns—demand explicit confirmation and invoke doca-hardware-safety; this skill adds only the BF3-specific operational sequence on top. Routes forward: bare-metal binary launch goes to doca-bare-metal-deployment; container deploy goes to doca-container-deployment.
What it helps with
- push a BFB image to BlueField-3 over RShim from the host
- bring up the TMFIFO management channel and DPU console
- recover a DPU that did not come back after bfb-install
- switch a BlueField-3 between DPU and separated-host modes
- verify a BlueField-3 installation
Example prompts for the agent
- Push a BFB image to my BlueField-3 using bfb-install
- bfb-install returned 0 but the DPU never came back — where do I start recovery
- How do I switch my BlueField-3 from DPU mode to separated-host mode
How to install doca-bf3-deployment
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf3-deployment -a claude-code2Manually: put the files in place
~/.claude/skills/doca-bf3-deployment/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/doca-bf3-deployment/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf3-deployment -a codex2Manually: put the files in place
.agents/skills/doca-bf3-deployment/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf3-deployment -a cursor2Manually: put the files in place
.cursor/skills/doca-bf3-deployment/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install NVIDIA/skills skills/doca-bf3-deployment2Manually: put the files in place
.github/skills/doca-bf3-deployment/SKILL.md1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf3-deployment -a gemini-cli2Platform CLI
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-bf3-deploymentManually: put the files in place
.devin/skills/doca-bf3-deployment/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-bf3-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-bf3-deployment
How do I install doca-bf3-deployment in Claude Code?
Run npx skills add NVIDIA/skills --skill doca-bf3-deployment -a claude-code, then open ~/.claude/skills/doca-bf3-deployment/SKILL.md.
What does doca-bf3-deployment do?
The skill handles BlueField-3 day-1 provisioning: pushing BFB over RShim from the host, setting up the TMFIFO management channel, verifying the install, and recovering a DPU that did not return after push.
Do I need a DOCA install on the host to use this skill?
The skill itself is a platform overlay and does not require DOCA to read. To run bring-up operations, you need a physical BlueField-3, RShim access (PCIe or USB), a DOCA-Host install on the host, and a BFB image from DOCA Downloads.
Source text
SKILL.md · Apache-2.0
---
license: Apache-2.0
name: doca-bf3-deployment
description: >
Use this skill for BlueField-3 (BF3) day-1 platform bring-up via the
classic RShim/BFB path: pushing a BlueField bundle (BFB) to the DPU
over RShim with bfb-install from the host, the host-to-DPU TMFIFO
management channel (tmfifo_net0, the 192.168.100.x convention), RShim
daemon state and console-over-rshim, DPU mode selection
(DPU/embedded-function vs separated-host/NIC mode) via mlxconfig,
post-BFB recovery, a six-state BlueField-state classifier, and
verifying the install (cat /etc/mlnx-release plus version checks).
Trigger even when the user does not say "BF3" — typical phrasings
include {push a BFB to my BlueField-3}, {bfb-install exited 0 but the
DPU never came back}, {ping 192.168.100.2 works but ssh fails}, or {is
DOCA on the host or the Arm side?}. BFB reflash, mlxconfig set, mode
changes, and firmware burns are destructive: require explicit
target-bound confirmation and load doca-hardware-safety. App launch,
container deploy, env install, and the BF4 BMC-Redfish path route
elsewhere.
metadata:
author: NVIDIA <[email protected]>
kind: library
doca_version: "3.5"
tags:
- doca
- bluefield-3
- deployment
compatibility: >
No DOCA install required to read this skill (it is a
platform-lifecycle overlay loaded against BF3 hardware); the
bring-up and validation steps within DO require a real
BlueField-3, host-side RShim access (PCIe or USB), the matching
DOCA-Host install, and a BlueField bundle (BFB) image downloaded
from the public DOCA Downloads page.
The validation steps require a live DOCA install.
---
# DOCA BlueField-3 (BF3) deployment
## Examples
- **"I have a BlueField-3 and a BFB — how do I push it?"** — RShim
plus bfb-install from the host. Exit 0 is not success until the
DPU is ready.
- **"bfb-install exited 0 but the DPU never came back."** — start
at the six-state classifier, not a second burn.
## Instructions
Follow Loading order below. Open the tasks companion for BFB push
and recover. Open the capabilities companion for the RShim/BFB
contract and safety overlay. Do not open every companion file.
**Where to start:** This skill is the bundle's home for **BlueField-3
day-1 platform bring-up** — taking a BF3 from "powered card in the
slot" (or a card that just came back broken from a BFB push) to
"Arm OS healthy, TMFIFO up, host PFs bound, four-way version match
closed, ready to run a workload". It owns the **classic RShim/BFB
path** that BF3 uses today; the newer BMC-Redfish provisioning path
is the sibling skill
`doca-bf4-deployment/SKILL.md` (the BF4
equivalent). If the user has a BF3 and needs to push a BFB, recover
a DPU that did not come back, or verify the install, open
the tasks companion and start at
`## configure`. If the question is *what shape
does the BF3 platform-bring-up surface even have*, start at
the capabilities companion. Once the BF3 is healthy, this
skill routes **onward** to the deployment skills — running a binary
goes to
`doca-bare-metal-deployment/SKILL.md`;
deploying a service container goes to
`doca-container-deployment/SKILL.md`.
Every **mutating** burn invoked from a bring-up step — the BFB
reflash itself, any `mlxconfig set` (including a DPU/separated-host
mode flip), a firmware burn, or a kernel-boot-parameter change — is
governed by the change-application meta-policy in
`doca-hardware-safety/SKILL.md`, which
the agent loads ALONGSIDE this skill. This skill adds only the
**BF3-specific operational sequencing** on top; it does NOT redefine
the preflight / OOB-console / maintenance-window / rollback
discipline that meta-policy owns.
## Audience
This skill serves **external DOCA operators bringing up a real
BlueField-3** — i.e. people who already have:
- a physical BlueField-3 in a host (or a standalone BF3 they can
reach over its console / management network),
- host-side RShim access to the DPU (the RShim userspace daemon and
the `/dev/rshim*` character-device tree present over the PCIe or
USB RShim interface), and
- a matching DOCA-Host install on the host plus a BlueField bundle
(BFB) image downloaded from the public DOCA Downloads page.
It is **not** for:
- BlueField-4 bring-up (the BMC-Redfish provisioning path) — route
to `doca-bf4-deployment/SKILL.md`, the
BF4 equivalent of this skill,
- kernel-driver or BlueField-OS developers contributing to `mlx5_*`
or the BFB image itself (outside the scope of
field deployment),
- operators who already have a healthy BF3 and just want to *run a
binary* (route to
`doca-bare-metal-deployment/SKILL.md`)
or *deploy a service container* (route to
`doca-container-deployment/SKILL.md`),
- fresh-no-hardware users with no DOCA install — route to
`doca-setup ## no-install`.
The skill teaches the agent the BF3 bring-up *procedure* and the
rules for quoting documented commands from the public BlueField
Platform Software Manual, the public DOCA Installation Guide, and
the MFT manual via
`doca-public-knowledge-map/SKILL.md`;
it does **not** invent `bfb-install` flag sets, BFB image filenames,
RShim character-device paths, `bf.cfg` schema keys, `mlxconfig`
parameter names, or TMFIFO subnets from memory. Where a fact is
already vetted in
`doca-bare-metal-deployment ## bluefield-lifecycle`,
this skill reuses that exact fact rather than restating a new one.
## When to load this skill
Load this skill when the user is doing **hands-on BlueField-3
platform bring-up over the RShim/BFB path**, or asking a
cross-cutting BF3 lifecycle question that is not specific to one
library's API. Concretely:
- Pushing a BFB image to a BF3 for the first time (or re-pushing
after a failed install), from the host over the RShim interface
with `bfb-install`.
- Bringing up or recovering the host-to-DPU TMFIFO management
channel (`tmfifo_net0`, the documented `192.168.100.x`
convention) and the RShim console.
- Confirming RShim driver/daemon state on the host (the userspace
`rshim` daemon and the `/dev/rshim*` tree) before any push or
console capture.
- Deciding (and routing) a DPU-mode change — DPU / embedded-function
mode vs separated-host / NIC mode — knowing the actual `mlxconfig
set` burn leaves this skill for
`doca-hardware-safety/SKILL.md`.
- Recovering a BF3 that did not come back after a BFB push:
`bfb-install` exited 0 but the DPU never reached the documented
`DPU is ready` marker; `ping 192.168.100.2` works but SSH refuses;
host PFs are present in `lspci -d 15b3:` but their netdevs are
gone.
- Verifying a BF3 install — `cat /etc/mlnx-release` on the Arm side,
the four-way version match per
`doca-version/SKILL.md` — and distinguishing
the host-side DOCA install from the BlueField-Arm-side DOCA
install.
- Cross-cutting questions: *"is DOCA on the host or on the Arm
side, and which one do I install?"*, *"my BF3 was fine last week
and after a BFB push it never came back — where do I start?"*,
*"how do I tell which `/dev/rshim<N>` is which BlueField on a
multi-DPU host?"*.
Do **not** load this skill for: BlueField-4 bring-up (route to
`doca-bf4-deployment/SKILL.md`, the BF4
equivalent); running a DOCA-linked binary on a healthy BF3 (route to
`doca-bare-metal-deployment/SKILL.md`);
deploying a DOCA service container (route to
`doca-container-deployment/SKILL.md`);
env-preparation including hugepages, IOMMU, pkg-config, and devlink
mode flips (use `doca-setup/SKILL.md`); the body of
the version-match rule (use `doca-version/SKILL.md`);
or any hardware-state-changing burn itself — the change-application
discipline is meta-policy owned by
`doca-hardware-safety/SKILL.md`, loaded
ALONGSIDE this skill.
## What this skill provides
This is a **thin loader**. Substantive material lives in two
companion files:
- the capabilities companion — the BF3 platform-bring-up contract: the
RShim/BFB transport surface (the userspace RShim daemon, the
`/dev/rshim*` tree, console-over-rshim, the BFB image as the unit
of input), the TMFIFO management-channel surface (`tmfifo_net0` /
`tm-br`, the documented `192.168.100.x` convention, the
`ip route get`-before-`ping` loopback gotcha), the DPU-mode
surface (DPU / embedded-function vs separated-host / NIC mode, set
via `mlxconfig` at BFB-install time — a MUTATING burn routed to
`doca-hardware-safety/SKILL.md`), the
host-side-vs-Arm-side DOCA install distinction, the
BF3-version overlay on the four-way match owned by
`doca-version/SKILL.md`, the cross-cutting error
taxonomy, the observability surface, and the safety policy
(overlay on
`doca-hardware-safety/SKILL.md`).
- the tasks companion — step-by-step workflows for the in-scope BF3
lifecycle verbs: `configure`, `build` (routing stub), `modify`,
`run` (the BFB-install + RShim/TMFIFO bring-up sequence), `test`
(the post-BFB readiness smoke), `debug` (the six-state
`bluefield-state-classifier`), and the `Deferred task verbs`
block routing app-launch / container / install / library-API /
hardware-state-change / BF4 questions out to their owning skills.
The skill assumes a target where:
- a BlueField-3 is physically present and powered, reachable from a
host that has the RShim daemon and `/dev/rshim*` tree available,
- the operator has a BFB image downloaded from the public DOCA
Downloads page (route via
`doca-public-knowledge-map/SKILL.md`),
and
- the operator has an out-of-band path (BMC console, serial-over-LAN,
or physical UART) to reach the BF3 if a push breaks the Arm OS.
It does **not** cover installing DOCA on a host from scratch (that
goes through `doca-setup/SKILL.md`), and it does
**not** cover BlueField-4 (that goes through
`doca-bf4-deployment/SKILL.md`).
## Loading order
1. Read this skill first to confirm the user's question is in
scope (BF3 platform bring-up over the RShim/BFB path; NOT BF4,
NOT app-launch, NOT a library-API question).
2. **For the bring-up contract (RShim/BFB transport, TMFIFO
channel, DPU-mode surface, host-vs-Arm install distinction,
BF3-version overlay, error taxonomy, observability surface, BF3
safety overlay), see the capabilities companion.**
3. **For step-by-step workflows — `configure`, `build` (routing
stub), `modify`, `run` (BFB install + RShim/TMFIFO bring-up),
`test` (post-BFB readiness smoke), `debug` (the six-state
`bluefield-state-classifier`), plus the `Deferred task verbs`
block — see the tasks companion.**
## Example questions this skill answers well
## What this skill deliberately does not ship
## Related skills
© NVIDIA · Apache-2.0 · NVIDIA/skills