Doca Flow Grpc Server Agent Skill

DOCA Flow gRPC Server (doca_flow_grpc)

> CRITICAL transport-security correction (Run-12 + R13). The

> shipped doca_flow_grpc / doca_flow_grpc_client

> binaries hard-code the gRPC plaintext credentials surface:

> the server uses grpc::InsecureServerCredentials() (the

> C++ gRPC server-side API in tools/flow_grpc_server/server/);

> the C++ client uses

> grpc::InsecureChannelCredentials() (the C++ gRPC

> client-side API; the client lives in

> libs/doca_flow/grpc/client/, compiled into the

> doca_flow library, NOT under tools/flow_grpc_client/);

> the **Python

> client** uses grpc.aio.insecure_channel(...). Do NOT cite the

> server-side string as grpc::InsecureChannelCredentials() —

> that is the client-side API name and a Grep-against-source

> verification will fail. There

> is no TLS, no mTLS, and no token-auth knob on the shipped

> control plane today. Any prose below (or in CAPABILITIES.md

> / TASKS.md) that frames "mTLS / token auth / TLS posture"

> as a configurable knob on this server is the bundle's

> previous aspirational framing and is wrong against the shipped

> source. Treat the server as **plaintext-on-a-trusted-segment

> only**: it MUST be bound on a control-plane-only network

> segment behind an external proxy, sidecar, or VPN

> that itself enforces TLS + identity. Any "TLS / mTLS / token-

> auth" discussion below is about the operator's external

> hardening layer, NOT a knob on this binary. Routing for an

> TLS / identity design discussion must stay on the selected

> external proxy, sidecar, or VPN; never route it to a

> shipped-today binary knob.

Where to start: This is a tool skill for standing up and

operating doca_flow_grpc, the DOCA-shipped gRPC remote-

control surface for doca-flow. Open TASKS.md and

start at ## configure to decide whether a

remote control plane is the right answer at all (vs talking to

libdoca_flow.so directly), then ## run for

the start → bind → one-client-smoke sequence, then

## test for the smoke-before-bulk loop that

gates any RPC that mutates Flow / dataplane state. Open

CAPABILITIES.md when the question is *what

the gRPC contract surface looks like* (the .proto files shipped

under the tool's source tree on the user's install), *which

external proxy / sidecar / VPN protects the plaintext server*, *which language bindings

the gRPC ecosystem covers*, or *how to interpret the server's

own logs alongside the live Flow application's logs*. If DOCA is

not installed, route to

doca-setup first; if the user has

not stood up doca-flow yet, route to

doca-flow FIRST — the gRPC

server is a remote control plane on top of the Flow library, not

a replacement for it.

Example questions this skill answers well

The CLASSES of doca_flow_grpc 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 a remote control plane for my Flow

pipeline, or should my client just link libdoca_flow.so

directly?"** — worked example: *"my client is a Python

service on a different host; can it program Flow rules

remotely?"*. Answered by the *when-to-use-gRPC* decision in

CAPABILITIES.md ## Capabilities and modes

+ the routing into

doca-flow when a direct

library link is the better answer.

• **"Where is the gRPC contract surface actually defined on my

install?"** — worked example: *"I want to generate a Python

client; where do I get the .proto file?"*. Answered by the

*the-.proto-file-is-the-source-of-truth* rule in

CAPABILITIES.md ## Capabilities and modes

+ the language-bindings discussion of standard gRPC tooling

(protoc + the language-specific gRPC plugin per the

official gRPC docs on grpc.io).

• **"How do I harden the gRPC endpoint so it isn't an open

door into my dataplane?"** — worked example: *"the server is

bound on 0.0.0.0; what should I do before exposing it?"*.

Answered by the *admin attack surface* posture in

CAPABILITIES.md ## Safety policy

+ the external protection / network-segment decision in

TASKS.md ## configure.

• **"How do I smoke ONE client end-to-end before opening the

server to the fleet?"** — worked example: *"my Python client

can dial the endpoint; what is the first RPC I run to prove

it talks to the live Flow application?"*. Answered by the

smoke-before-bulk loop in

TASKS.md ## test +

CAPABILITIES.md ## Safety policy

smoke-before-bulk rule.

• **"My client cannot reach the server — is the server down,

the wrong endpoint, an external-proxy mismatch, or a version

mismatch?"** — worked example: *"the client times out

connecting"*. Answered by the layered error taxonomy in

CAPABILITIES.md ## Error taxonomy

+ the layered ladder in

TASKS.md ## debug.

• **"Is my non-C++ client (Python / Go / Rust) actually the

right shape for the gRPC contract, or is there a cleaner

path?"** — worked example: *"I want a Rust client; what

does the .proto-generated API look like?"*. Answered by the

language-bindings discussion in

CAPABILITIES.md ## Capabilities and modes

+ the routing through standard gRPC tooling.

Audience

This skill serves **external operators, control-plane developers,

and AI agents who need to program a running DOCA Flow pipeline

from a non-C++ process across a network boundary** instead of

linking libdoca_flow.so directly into the controlling process.

Concretely:

• A control-plane engineer writing a Python / Go / Rust client

that programs Flow rules on a BlueField from outside the

BlueField's address space.

• A platform operator running a Flow-using service on

BlueField who wants to expose a remote-control surface to a

centralized control plane.

• An AI agent driving the *"can I program these Flow rules

from this client / this network position"* triage step

before recommending a code change to the surrounding

doca-flow application.

It is not for users debugging the gRPC server's source code,

not a substitute for the live public DOCA Flow gRPC Server

guide on docs.nvidia.com, and not the place to learn the

doca-flow API — that audience belongs in

doca-flow.

doca_flow_grpc is a **single CLI binary built from the DOCA

source tree** (executable('doca_flow_grpc', ..., install: false)

in tools/flow_grpc_server/meson.build, gated by

flag_enable_grpc_support), plus its companion .proto

contract files under libs/doca_flow/grpc/; per the tool's

source tree (server/, dpa_device/, packet_buffering/) the

tool can also be paired with a packet-buffering / DPA-side

helper on configurations that need them. The skill uses the

same kind: tool three-file shape (SKILL.md + CAPABILITIES.md + TASKS.md) the rest of the bundle's tool slot uses — front matter at the top of this file already says kind: tool. (Prior bundle revisions said "library three-file shape" here; that wording was internally inconsistent with the front matter and is corrected.)

Language scope

This skill governs deployment, configuration, hardening, and

client-side bring-up across the languages standard gRPC tooling

covers — Python, Go, C++, Rust, Java, Node.js, C#, Kotlin, Ruby,

PHP, Dart — via the language-specific gRPC plugin generated

from the shipped .proto files (see the

gRPC language support index

on grpc.io). The server itself is C++ + DOCA; the client

languages are open, gated only by the standard protoc plugin

set. For the doca-flow API the server programs, see

doca-flow — that surface is

C-language.

When to load this skill

Load this skill when the user is — or the agent needs to — bring

up doca_flow_grpc against a running doca-flow

application (or its preconditions) and connect a non-C++ client

to it. Concretely:

• Deciding whether a remote gRPC control plane is the right

surface (vs a direct libdoca_flow.so link in the client

process).

• Locating the .proto files on the user's install so a

language-binding client can generate the appropriate

stubs.

• Deciding the deployment's transport-security posture and

network segment. NOTE: the shipped server is plaintext-only

(grpc::InsecureServerCredentials()); TLS / mTLS / token-auth

are NOT binary configuration knobs — they are external

infrastructure concerns handled by a capable proxy, sidecar,

or VPN, and the

plaintext endpoint must stay on a trusted, isolated segment.

• Standing up the server alongside a known-good Flow setup

and smoke-testing one client end-to-end before exposing

the endpoint to the fleet.

• Diagnosing a connect / version / RPC failure through the

layered taxonomy.

Do not load this skill for general DOCA orientation,

doca-flow API work, DOCA install, or general gRPC tooling

(use the grpc.io docs directly for those).

What this skill provides

This is a thin loader. Substantive material lives in two

companion files:

• CAPABILITIES.md — what doca_flow_grpc exposes:

the gRPC remote-control surface in front of doca-flow,

the .proto-files-as-authoritative-contract rule (the

shipped .proto files under the tool's source on the

user's install are the source of truth), the *when-to-use-

gRPC vs direct-library-link* decision, the language-

bindings story (any language standard gRPC tooling covers),

the external proxy / sidecar / VPN and network-segment decision, the

packet-buffering / DPA-side option per the shipped

packet_buffering/ and dpa_device/ subtrees, the

version overlay (server rides the doca-flow library

version it links against), the layered error taxonomy

(server-not-started / server-binding-failed / external-layer-

rejected / RPC-call-error / Flow-precondition-failed /

version / cross-cutting), the observability surface (the

server's own logs + the live Flow application's logs +

the RPC client's status codes), and the safety policy

that treats the endpoint as an admin attack surface.

• TASKS.md — step-by-step workflows for the in-scope task

verbs: install (route to setup; binary is built from

source with gRPC support enabled),

configure (decide remote-vs-direct, pick the external

proxy / sidecar / VPN and network segment), build (route to install),

modify (refuse — modify the deployment, not the binary),

run (start → bind → smoke), test (the

smoke-before-bulk loop with the client-side stub

generation step), debug (the layered diagnosis ladder),

use (the agent-side workflow for consuming a captured

gRPC server session), plus a Deferred task verbs block

and a Command appendix.

The skill assumes a host where DOCA is already installed (or

the NGC DOCA container is running) with the Flow library

present, a working doca-flow application to program against,

and the operator's awareness that exposing a gRPC control plane

is a high-stakes posture.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or scripts

bundle. To keep the boundary clean, it deliberately does not

contain — and pull requests should not add:

• **Verbatim RPC method names, message field inventories, or

default endpoint paths.** The .proto files shipped under

the tool's source tree on the user's install are the

authoritative contract; copying them here pins the skill

to one release and silently rots when the contract

evolves.

• Pre-baked client code in any language. The

language-specific gRPC plugin + the shipped .proto files

are the contract; client code generated from them on the

user's installed version is the right answer, not a stub

pinned to a snapshot.

• A pre-baked external security-layer configuration. CA,

token, and mTLS configuration belong to the selected proxy,

sidecar, or VPN and its security review, never to

doca_flow_grpc.

• Wrappers, parsers, or scripts that proxy the gRPC

endpoint into another protocol. The endpoint is the

endpoint; if a user wants HTTP/JSON instead, that is a

separate concern outside this skill's scope.

• A samples/, bindings/, or reference/ subtree.

Even one labeled *"reference"* is misleading: operators

will read it as buildable.

Loading order

• Read this SKILL.md first to confirm the user's question

is in scope (the user actually wants a remote gRPC control

plane on top of doca-flow, not a direct library link or

a different DOCA library).

• **For what the server exposes, the .proto-as-contract

rule, the language-bindings story, the external proxy /

sidecar / VPN and network-segment decision, version availability, the

layered error surface, observability, and safety posture,

see CAPABILITIES.md.**

• **For the documented start sequence and the

smoke-before-bulk workflow — install, configure,

build, modify, run, test, debug, use — see

TASKS.md.**

Related skills

• doca-flow — the **base

library** the server's gRPC contract is a thin remote-

control wrapper over. Pipe / entry / rule semantics, the

validate-before-commit rule, the Flow counter / inspector

surface all live there.

• doca-flow-tune — the Flow

tuning tool. When a Flow-program change is recommended,

the change can be applied through the surrounding

application or — when the control plane is remote —

through this gRPC server's RPC surface.

• doca-public-knowledge-map

— routing to the public DOCA Flow gRPC Server page on

docs.nvidia.com and the rest of the public DOCA

documentation set.

• doca-version — canonical

version-handling rules. The

## Version compatibility

section in this skill is a thin overlay on top.

• doca-debug — the cross-cutting

debug ladder. gRPC server failures route into the ladder at

the runtime layer.

• doca-setup — env preparation,

install verification, and the NGC DOCA container path.

• doca-hardware-safety —

the cross-cutting hardware-safety meta-policy this skill's

## Safety policy overlays. Any state-changing RPC is a

potential dataplane-affecting change and must respect the

meta-policy.