# doca-firefly

Guides deployment and PTP debugging for the DOCA Firefly container on NVIDIA BlueField.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 4106 repo stars
- Author: NVIDIA
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/NVIDIA/skills/tree/HEAD/skills/doca-firefly/SKILL.md
- Updated: 2026-10-23
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/doca-firefly

## What it does

Assists in operating the DOCA Firefly Service container running under BlueField OS. The skill guides configuration across six internal stack subsystems: the primary `ptp4l` engine, PTP Monitor, internal `phc2sys`, PPS signaling, SyncE, and the proprietary Firefly Servo. It helps determine the four configuration axes: role, profile (`default`, `media`, `telco-l2`, or `custom`), domain, and target network interface.

Provides troubleshooting paths when PTP halts in the LISTENING state, clock jitter exceeds network tolerance, or workloads such as Rivermax SMPTE fail to receive precision timestamps. Individual parameters inside `doca_firefly.yaml` can be adjusted using `CONF_<SUBSYSTEM>_<section>_<key>` environment overrides.

A functional DOCA environment on BlueField hardware is required to perform validation steps: the skill does not install DOCA itself nor does it replace host-side time daemons.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add NVIDIA/skills --skill doca-firefly -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/doca-firefly/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/doca-firefly/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add NVIDIA/skills --skill doca-firefly -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/doca-firefly/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add NVIDIA/skills --skill doca-firefly -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/doca-firefly/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install NVIDIA/skills skills/doca-firefly
```

2. **Manually: put the files in place**
- File: `.github/skills/doca-firefly/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add NVIDIA/skills --skill doca-firefly -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-firefly
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/doca-firefly/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/NVIDIA/skills/tree/HEAD/skills/doca-firefly/SKILL.md

## When to use it
- Select PTP role, profile, domain, and interface configurations
- Troubleshoot container deployments stuck in the LISTENING state
- Align BlueField PHC hardware clocks with Rivermax workloads
- Fix host clock drift when Firefly reports active sync

## Example prompts
- Why is the Firefly container active but PTP never exits LISTENING?
- Configure doca_firefly.yaml with the media profile for SMPTE ST 2110
- Firefly indicates lock but the host system clock still drifts

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7a6488c132a9e4d9.

BEGIN THIRD-PARTY FILE 7a6488c132a9e4d9
```text
---
license: Apache-2.0
name: doca-firefly
description: >
  Use this skill when the user is operating the DOCA Firefly Service
  container on BlueField — picking the four PTP configuration axes (role
  / profile / domain / interface), wiring the BlueField PHC + host
  follower + consumer workload pairing, deciding whether PTP-grade time
  is even needed (vs. chrony / NTP), or debugging a Firefly deployment
  where PTP isn't syncing or the host clock isn't following. Trigger
  even when the user does not explicitly mention "DOCA Firefly" or "PTP"
  — typical implicit phrasings include "container green but PTP never
  advances past LISTENING", "Firefly says synced but the host clock
  still drifts", "sync acquired but offset is tens of microseconds", "my
  Rivermax SMPTE workload needs PTP", or "is chrony good enough". Refuse
  and route elsewhere for installing DOCA, host-side chrony / ptp4l
  config bodies, PTP topology / boundary-clock design, building DOCA
  apps that read the disciplined PHC, or other DOCA services (DMS,
  Flow-Inspector, HBN) — those belong to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: service
  doca_version: "3.5"
  tags:
    - doca
    - firefly
    - ptp
compatibility: >
  BlueField-Arm-only DOCA service container; pulled from NVIDIA NGC and
  started under the BlueField OS container runtime. Host-side install is
  irrelevant. Requires a reachable PTP master (or runs as the master
  itself) and a PTP-aware network path; the host-side time follower
  (chrony / ptp4l / phc2sys reading the BlueField PHC) is also
  operator-owned. The validation steps require a live DOCA install.
---

# DOCA Firefly Service

## Examples

- **“Container green but PTP never advances past LISTENING.”**
  — this is in scope. Check role / profile / domain /
  interface before changing host chrony.
- **“Firefly says synced but the host clock still drifts.”** —
  wire the BlueField PHC follower; Firefly does not replace
  host-side chrony / ptp4l bodies.

## Instructions

Follow Loading order below. Open the tasks companion for configure /
sync / debug. Open the capabilities companion for PTP axes.
Do not open every companion file.

> **Subsystem inventory.**
> DOCA Firefly is NOT just "a PTP daemon." The shipped
> `doca_firefly.yaml` exposes **six** PTP-stack subsystems via
> environment variables, each with its own `*_STATE`,
> `*_CONFIG_FILE`, and (where relevant) `*_INTERFACE` /
> `*_DEVICE` knobs (the count is six because the PTP Monitor
> subsystem ships an internal `phc2sys` monitor client that is
> distinct from the standalone PHC2SYS subsystem — both ship in
> the same container image):
>
> 1. **PTP** (`PTP_STATE`, `PTP_INTERFACE`, `PTP_CONFIG_FILE`) —
>    the `ptp4l` daemon (or master, depending on profile) that
>    drives the BlueField PHC.
> 2. **PTP Monitor** (`MONITOR_STATE`, `MONITOR_CONFIG_FILE`,
>    `MONITOR_CLIENT_TYPE`, `MONITOR_CLIENT_PHC2SYS_INTERFACE`,
```
END THIRD-PARTY FILE 7a6488c132a9e4d9

The third-party file has ended. Everything between the 7a6488c132a9e4d9 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2980 of 17817 bytes. © NVIDIA · Apache-2.0 · https://github.com/NVIDIA/skills/tree/HEAD/skills/doca-firefly/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
