Doca Firefly

NVIDIAOfficialCreated by NVIDIA

Skill
Tool integration
Cloud and DevOps
Apache-2.0
Medium risk

From the author

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.

— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The doca-firefly skill provides guidance for deploying and managing the DOCA Firefly Service container on BlueField DPU hardware. It focuses on configuring PTP-related subsystems, including PTP, PHC2SYS, PPS, SyncE, and the Firefly Servo, to ensure precise time synchronization. The skill covers the four primary PTP configuration axes (role, profile, domain, and interface), the necessary wiring of the BlueField PHC to host-side followers, and troubleshooting common synchronization issues. It is designed for operators managing time-sensitive workloads like SMPTE ST 2110, 5G UPF, or distributed databases that require sub-microsecond precision.

What it does

Guides the deployment and configuration of the DOCA Firefly Service container.
Explains the four PTP configuration axes: role, profile, domain, and interface.
Details the integration between the BlueField PHC and host-side time followers.
Provides troubleshooting steps for PTP synchronization failures and clock drift.
Outlines the six internal PTP-stack subsystems managed within the Firefly container.
Defines the operational boundary between Firefly and consumer workloads like Rivermax.

When to use it

When deploying the DOCA Firefly Service container on BlueField Arm.
When determining if PTP-grade time is required versus standard NTP/chrony.
When configuring PTP roles, profiles, and domains for a specific network environment.
When debugging PTP sync issues or host clock drift relative to the BlueField PHC.
When pairing Firefly with time-sensitive workloads like Rivermax SMPTE.

Advantages

Provides a structured approach to complex PTP configuration on BlueField.
Clarifies the distinction between container-internal and host-side time synchronization.
Offers a clear taxonomy for debugging PTP state and offset issues.
Ensures consistent configuration of PTP axes across different deployment scenarios.

Usage examples

“My Firefly container is running but PTP is stuck in LISTENING state.”: The agent will guide you through checking the four PTP configuration axes (role, profile, domain, and interface) to ensure they match your network topology.
“Firefly reports it is synced, but my host clock is still drifting.”: The agent will help you verify the host-side follower configuration (e.g., chrony or ptp4l) to ensure it is correctly reading the disciplined BlueField PHC.
“Do I need Firefly for my distributed application, or is chrony enough?”: The agent will help you evaluate your time-precision requirements to decide if PTP-grade synchronization is necessary for your specific workload.
“How do I pair Firefly with a Rivermax SMPTE workload?”: The agent will explain how Firefly disciplines the PHC and how to correctly configure the Rivermax workload to consume that time source.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/doca-firefly/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip doca-firefly.zip -d .agents/skills

Documentation by NVIDIA

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):
PTP (PTP_STATE, PTP_INTERFACE, PTP_CONFIG_FILE) — the ptp4l daemon (or master, depending on profile) that drives the BlueField PHC.
PTP Monitor (MONITOR_STATE, MONITOR_CONFIG_FILE, MONITOR_CLIENT_TYPE, MONITOR_CLIENT_PHC2SYS_INTERFACE, MONITOR_CLIENT_CONNECTION_TIMEOUT) — the monitor server + client surface; the internal phc2sys monitor client (MONITOR_CLIENT_TYPE=phc2sys) is a real subsystem inside Firefly, not just a host-side concern.
PHC2SYS (PHC2SYS_STATE, PHC2SYS_ARGS, PHC2SYS_CONFIG_FILE) — the container-internal phc2sys instance (not host-only).
PPS (PPS_STATE, PPS_DEVICE) — the Pulse-Per-Second output (with the additional enable_while_running and do_nothing states beyond plain enable/disable).
SyncE (SYNCE_STATE, SYNCE_INTERFACE, SYNCE_CONFIG_FILE) — Synchronous Ethernet frequency distribution; orthogonal to PTP.
Firefly Servo (SERVO_STATE, SERVO_CONFIG_FILE) — the proprietary Firefly servo loop (alternative to the upstream linuxptp servo).
The valid PROFILE values are exactly default / media / telco-l2 / custom (per doca_firefly.yaml comments) — the agent must not invent additional values. Subsystems configured as defined_by_profile are controlled by the active PROFILE.
Configuration-override env vars follow the pattern CONF_<SUBSYSTEM>_<section>_<key> (e.g. CONF_PTP_global_priority1, CONF_SYNCE_global_backend, CONF_MONITOR_global_telemetry_export); these are the documented surface for overriding individual config keys without shipping a full custom config file.
Configuration hierarchy: the mounted Firefly config file is mandatory and owns the primary PTP axes (role, profile, domain, interface, and transport). CONF_<SUBSYSTEM>_<section>_<key> variables are optional, documented per-key overrides of that file; they are not a second standalone configuration model.

Where to start: This skill is for operating the DOCA Firefly Service container, not for linking against a library. Firefly is the PTP / PHC2SYS / PPS / SyncE / Servo / Monitor stack that drives and observes the BlueField PTP Hardware Clock (PHC); it is not the host-side time follower, not the consumer workload, and not a programming surface. If the user wants to deploy the container, open the tasks companion and start at ## configure. If the question is what shape of service is Firefly and what PTP roles / profiles does it speak, start at the capabilities companion. If DOCA is not installed on the BlueField yet, route to doca-setup/SKILL.md first. If the user's real question is “I have a Rivermax SMPTE workload and the docs say I need PTP”, the right pairing is this skill plus doca-rmax/SKILL.md — Firefly disciplines the PHC; Rivermax reads the disciplined time.

Example questions this skill answers well

The CLASSES of Firefly questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

“Do I actually need Firefly, or is NTP / chrony good enough?” — worked example: “my distributed app is fine on chrony today; is there a reason to add PTP?”. Answered by the PTP-vs-NTP path- selection rule in the capabilities companion
- the env-prep checklist in the tasks companion.
“What four PTP configuration axes do I have to decide before starting the container?” — worked example: “a SMPTE ST 2110 broadcast plant that wants Firefly in slave role on the wire-side port”. Answered by the four-axis configuration table in the capabilities companion
- the PTP-config step in the tasks companion.
“Firefly's container is running but the host's time isn't following — what did I miss?” — worked example: “ptp4l / Firefly says it's locked but chronyc tracking on the host shows drift”. Answered by the END-TO-END time-sync discipline in the capabilities companion
- the host-follower step in the tasks companion.
“PTP locks but the offset / jitter is way past spec — what's wrong with the path?” — worked example: “sync acquired but offset is in the tens of microseconds”. Answered by the PTP-aware-path rule in the capabilities companion
- the layered debug ladder in the tasks companion.
“How does Firefly pair with a Rivermax SMPTE workload?” — worked example: “SMPTE ST 2110 video sender that needs to be PTP- locked”. Answered by the Rivermax-pairing rule in the capabilities companion
- the pairing step in the tasks companion, which routes the Rivermax side to doca-rmax/SKILL.md and refuses to collapse the two services into one.
“My Firefly container starts but PTP never reaches SLAVE / MASTER state — was it role, domain, profile, or interface?” — worked example: “container green but the ports-state output never advances past LISTENING”. Answered by the four-axis-mismatch rule in the capabilities companion
- the layered ladder in the tasks companion.

Audience

This skill serves external operators and platform teams who deploy the DOCA Firefly Service container to provide PTP-grade time synchronization to time-sensitive workloads on BlueField + the host behind it. Concretely: people running the Firefly container on BlueField Arm, choosing its PTP role / profile / domain / interface from the public Firefly guide, wiring the host-side follower (chrony with the PHC source, or ptp4l reading the PHC) so the host clock tracks the BlueField PHC, and validating the end-to-end discipline before scaling a Rivermax, 5G UPF, financial-trading, or distributed- database workload that depends on it.

It is not for NVIDIA developers contributing to Firefly itself, nor a programming guide for building on DOCA libraries (see doca-programming-guide/SKILL.md). Firefly is a service: the operator runs a container and configures PTP; there is no libfirefly.so to link against.

Path selection up front. Use Firefly when sub-microsecond, PTP-grade time precision is required on BlueField AND the host (SMPTE ST 2110 broadcast workloads layered on Rivermax, 5G UPF time requirements, distributed systems that need PTP-grade time, anything where NTP / chrony jitter is not tight enough). Do not reach for Firefly when NTP / chrony already meets the workload's time-precision budget, when no PTP-aware switching / boundary-clock infrastructure exists in the path, or when pure software-side time precision is sufficient — in those cases the correct answer is to keep the host's existing chrony / NTP setup and route the agent away from Firefly, not to deploy it speculatively.

When to load this skill

Load this skill when the user is doing hands-on Firefly deployment work on a BlueField where DOCA is already installed. Concretely:

Deciding whether Firefly is the right answer for the user's time-precision requirement (vs. keeping NTP / chrony on the host).
Deploying the Firefly container on BlueField Arm — choosing image source per the public DOCA Firefly Service Guide, mounting the Firefly config, and starting / stopping the container.
Choosing the four PTP configuration axes — PTP role (master / slave / boundary clock / transparent clock), profile (the PROFILE env var accepts EXACTLY default / media / telco-l2 / custom per the shipped doca_firefly.yaml; these map onto industry PTP profile names: default → IEEE 1588, media → SMPTE 2059-2, telco-l2 → G.8275.1 only (G.8275.2 corresponds to the separate telco-l3 config, reached via custom) — do NOT put the industry names directly into the env var), domain number, network interface — for the user's deployment.
Wiring the host-side follower so the host clock tracks the BlueField PHC (chrony with the PHC source, or ptp4l / phc2sys reading the PHC) — without this step the host clock does NOT follow the Firefly-disciplined PHC, regardless of how cleanly Firefly comes up.
Pairing Firefly with a time-sensitive consumer workload (Rivermax SMPTE, 5G UPF, finance, distributed databases) and validating the end-to-end discipline.
Reading the Firefly container's logs, the PHC offset, the ports-state output, or any other documented observability surface to confirm PTP is locked.
Debugging a Firefly deployment where the container is healthy but PTP is not syncing, or PTP is syncing but the host clock is not following, or sync is up but jitter is past spec.

Do not load this skill for general DOCA orientation, install of DOCA itself, library-API questions, or non-PTP time topics. For those, route via doca-public-knowledge-map/SKILL.md, doca-setup/SKILL.md, or the matching libs/<library> skill.

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

the capabilities companion — Firefly's architecture (container that drives the BlueField PHC and speaks PTP on the wire), the four PTP configuration axes (role / profile / domain / interface, with transport as a fifth knob), the deployment shape (container on BlueField Arm per the public Container Deployment Guide), the pairing surface (Rivermax + host-side time-sync follower), the observability surface (container logs + PHC offset + ports state), the error taxonomy (four-axis-mismatch / host-follower / PTP-aware- path / container-runtime), and the safety policy (PTP-vs-NTP path selection, END-TO-END discipline, smoke-before-scale).
the tasks companion — step-by-step workflows for the in-scope Firefly verbs: configure, build, modify, run, test, debug, plus a Deferred task verbs block routing out-of-scope questions and a Command appendix of recurring commands.

The skill assumes a BlueField where DOCA is already installed and the operator has the privileges the public Firefly Service Guide expects to pull, run, and configure containers on BlueField Arm. It does not cover installing DOCA — that path goes through doca-setup/SKILL.md.

What this skill deliberately does not ship

This skill is agent guidance, not a templates or sample-config bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:

Pre-baked Firefly configuration files (full PTP config blocks, ready-to-run role / profile / domain bundles) intended to be copy-pasted into production. PTP configuration is deployment- specific (per the user's profile, domain plan, interface naming, and upstream PTP topology); the safe answer for an external operator is to derive the config from the public Firefly Service Guide against their own deployment. The agent's job is to prescribe the procedure and the four-axis decision, not to ship a config the user might run unmodified.
Container image names, tags, or registry paths. The authoritative image source is the public DOCA Firefly Service Guide reachable through doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services); Firefly's image tag is version-bound and changes between DOCA releases. Inventing or memorizing a tag is the canonical hallucination failure mode for a service skill.
Host-side chrony stanzas or ptp4l / phc2sys config files. Those are host-environment-specific and live on the host, not inside the Firefly container. The skill names that the host-side follower must be wired and what its source must be (the BlueField PHC); the chrony / ptp4l config bodies belong to the host operator and to upstream Linux PTP documentation.
A samples/, templates/, or reference/ subtree of any kind. A mock or incomplete artifact in this skill's tree, even one labeled “reference”, is misleading: operators will read it as production-ready.

Loading order

Read this skill first to confirm the user's question is in scope and that Firefly is the right answer at all (vs. keeping NTP / chrony on the host).
For Firefly's deployment shape, the four PTP configuration axes, the Rivermax + host-follower pairing surface, the error taxonomy, the observability surface, and the END-TO-END safety policy, see the capabilities companion.
For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion.

doca-public-knowledge-map/SKILL.md — the routing table to the public DOCA Firefly Service Guide and the rest of the public DOCA documentation set. The Firefly URL is listed under ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services).
doca-setup/SKILL.md — env preparation and install verification on the BlueField where the Firefly container will run, including the I have no install yet path via the public NGC DOCA container. This skill assumes its preconditions are satisfied on BlueField Arm.
doca-version/SKILL.md — canonical DOCA version-handling rules. Firefly's container tag is version-bound; this skill's ## Version compatibility cross-links the four-way match rule and adds the container-tag-lags-host-package overlay.
doca-structured-tools-contract/SKILL.md — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in the tasks companion honors this contract.
doca-programming-guide/SKILL.md — general DOCA patterns. Firefly is service-shaped not library- shaped, so the build / modify / first-app pattern there does not apply directly, but the cross-library debug discipline (frontend- before-backend, env-before-program) remains useful when Firefly reports an error that originated in the container runtime or in a DOCA library it called.
doca-rmax/SKILL.md — the canonical paired workload. SMPTE ST 2110 Rivermax streams depend on a Firefly-disciplined PHC; Firefly is the time-source side and Rivermax is the timing-precise data-plane side. The two skills load together for any broadcast-style deployment, and they do NOT collapse into one another — Firefly does not stream media; Rivermax does not discipline the PHC.
doca-dms/SKILL.md — sibling service skill. The agent reading both skills should see the same service-skill shape (container, BlueField Arm, deployment pattern, smoke-before-scale, env preconditions, config schema) layered on top of a different per-service domain (DMS = device management via gNMI / gNOI; Firefly = time synchronization via PTP).
doca-debug/SKILL.md — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Firefly-specific debug (PTP not syncing, host clock not following, jitter past spec) overlays on top of that ladder.

Files

ATTRIBUTION.mdAdded by AutoGineer894 B
BENCHMARK.md9.9 KiB
CAPABILITIES.md22.8 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md17.4 KiB
SKILLCARD.yaml2.7 KiB
TASKS.md29.1 KiB
evals/evals.json2.5 KiB
skill-card.md5.2 KiB
skill.oms.sig5.1 KiB

SKILLCARD.yaml

# SKILLCARD.yaml — skill identity and routing metadata (canonical card: skill-card.md)
# Schema: https://github.com/NVIDIA/skills/blob/main/docs/skill-cards.mdx

schema_version: "1"

identity:
  name: "doca-firefly"
  artifact_id: "doca-firefly"
  kind: "service"
  version: "TBD-at-sign-time"          # NVCARPS fills from the source ref
  signature: "TBD-at-sign-time"        # NVCARPS-generated SHA + ed25519 sig
  signed_by: "TBD-at-sign-time"        # NVCARPS identity (NVIDIA-PSIRT signing key)

description: "Use this skill when the user is operating the DOCA Firefly Service\ncontainer on BlueField — picking the four PTP configuration axes\n(role / profile / domain / interface), wiring the BlueField PHC +\nhost follower + consumer workload pairing, deciding whether\nPTP-grade time is even needed (vs. chrony / NTP), or debugging a\nFirefly deployment where PTP isn't syncing or the host clock isn't\nfollowing. Trigger even when the user does not explicitly mention\n\"DOCA Firefly\" or \"PTP\" — typical implicit phrasings include\n\"container green but PTP never advances past LISTENING\", \"Firefly\nsays synced but the host clock still drifts\", \"sync acquired but\noffset is tens of microseconds\", \"my Rivermax SMPTE workload needs\nPTP\", or \"is chrony good enough\". Refuse and route elsewhere for\ninstalling DOCA, host-side chrony / ptp4l config bodies, PTP\ntopology / boundary-clock design, building DOCA apps that read the\ndisciplined PHC, or other DOCA services (DMS, Flow-Inspector, HBN)\n— those belong to other skills."

source:
  repo: "NVIDIA-DOCA/doca-skills"
  path: "skills/services/doca-firefly/SKILL.md"
  branch: "main"
  license: "Apache-2.0 AND CC-BY-4.0"

provenance:
  scan_run_id: "TBD-at-sign-time"      # NVCARPS scan run UUID
  signed_at:   "TBD-at-sign-time"      # ISO-8601 timestamp from NVCARPS
  upstream_catalog: "https://github.com/NVIDIA/skills"
  upstream_component: "doca"

quality:
  canonical_card: "skill-card.md"     # signed card with evaluation results
  benchmark: "BENCHMARK.md"

behavior_boundaries:
  documentation_only: true             # bundle ships no runnable code
  hardware_touching_changes_routed_to: "skills/doca-hardware-safety/"
  version_policy_routed_to: "skills/doca-version/"
  external_productized_software_routed_to: "skills/doca-public-knowledge-map/"
  see_also:
    - "AGENTS.md"                       # universal rules
    - "BENCHMARK.md"                    # how this skill is graded
    - "SECURITY.md"                     # safety-bug intake

contact:
  bug_intake: "https://github.com/NVIDIA-DOCA/doca-skills/issues"
  safety_bug_intake: "https://github.com/NVIDIA-DOCA/doca-skills/issues/new?labels=safety-bug"
  security:   "https://www.nvidia.com/en-us/security/"

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: 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.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/doca-firefly · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-firefly.zip