Doca Socket Relay

DOCA Socket Relay

Where to start: This is a tool skill for invoking the DOCA Socket

Relay — the host ↔ BlueField bridge that lets a socket-oriented host

application terminate its sockets locally while the relay forwards

the traffic to a DPU-side terminator across the DOCA fabric. Open

TASKS.md and start at ## configure

for the deployment-shape × socket-type × forwarding-endpoint

decision, then ## run for the bind → connect →

round-trip flow. Open CAPABILITIES.md when the

question is *what state can the relay carry, what does it report,

and what does its data-path posture imply*. If the user has not

installed DOCA yet, route to

doca-setup first. If the user is

asking about the host ↔ DPU control plane rather than the

data plane the relay carries, route to

doca-comch — the relay is the

data-plane counterpart to comch.

Example questions this skill answers well

The CLASSES of socket-relay 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.

• **"Can I move my existing socket-based application onto a DOCA

fabric without rewriting it?"** — worked example: *"a host service

speaks a socket protocol to a peer; I want the peer to live on

the BlueField DPU instead, but I do not want to port the

application to the comch programming surface"*. Answered by the

use-case framing in

CAPABILITIES.md ## Capabilities and modes

+ the deployment-shape decision in

TASKS.md ## configure.

• **"Where does the relay sit, and what runs on the host vs the

DPU?"** — worked example: *"do I run one relay process on the

host, a sidecar next to my app, or a relay container on the

BlueField — and what is on the DPU side that actually terminates

the connection?"*. Answered by the three-axis configuration model

(deployment shape × socket type × forwarding endpoint) in

CAPABILITIES.md ## Capabilities and modes

+ TASKS.md ## configure step 2.

• "My relay is up but the host application cannot connect." —

worked example: *"the relay process is running but the host app

reports ECONNREFUSED / connect timeout when it tries the

socket / port the relay should be listening on"*. Answered by the

layered error taxonomy in

CAPABILITIES.md ## Error taxonomy

layers 1-3 + the bind / accept ladder in

TASKS.md ## debug.

• "Bytes leave the host but never arrive on the DPU side." —

worked example: *"the host app's socket connect succeeded, the

relay reports the connection accepted, but the DPU-side

terminator never sees the data"*. Answered by the

forwarding-endpoint layer in

CAPABILITIES.md ## Error taxonomy

layer 4 + the silent-data-path failure mode named in

CAPABILITIES.md ## Safety policy.

• **"How do I prove the relay is the right answer before I admit

the whole fleet onto it?"** — worked example: *"I have N host

clients; I want to confirm one of them works end-to-end before

pointing the rest at the relay"*. Answered by the

smoke-before-bulk loop in

TASKS.md ## test (bind → confirm one host app

connects → confirm one round-trip end-to-end → only then admit

the fleet).

• **"Is this Socket Relay shipped on my installed DOCA, and does

its version match the comch / eth pieces it sits on?"** — worked

example: *"is the relay binary present on this host, and does

it agree with pkg-config --modversion doca-common"*. Answered

by the version overlay in

CAPABILITIES.md ## Version compatibility,

which redirects to the canonical

doca-version rules and adds the

Socket Relay specifics (presence check, host vs BlueField

packaging, agreement with companion libraries).

Audience

This skill serves **external operators, application owners, and AI

agents who need to bridge a socket-oriented application onto a

BlueField DPU without rewriting the application against the DOCA

programming surface**. Concretely:

• A platform owner with an existing host service that speaks a

socket protocol to a peer and wants the peer to live on the

BlueField instead — without porting the host service onto

doca-comch.

• A migration engineer evaluating the relay as the *first* step of

a phased move onto DOCA, with the comch / RDMA / Ethernet

rewrite reserved for a later phase.

• An SRE / platform operator deploying the relay as a service

container on the BlueField via the runtime contract documented

in doca-container-deployment.

• An AI agent answering *"my host app cannot reach the DPU on the

socket I configured — what do I check"* with the relay's layered

error surface as the diagnosis ladder.

It is not for users debugging the Socket Relay binary itself,

not a substitute for the live public DOCA Socket Relay guide,

and not the right place for users learning the comch

programming API or for users doing line-rate raw-packet I/O. Those

audiences belong in doca-comch

and doca-eth respectively.

The Socket Relay is shipped as a documented DOCA artifact on

installs that include it; depending on the operator's deployment

shape, it can be invoked as a CLI on the host or BlueField Arm, or

deployed as a service container on the BlueField via the

documented kubelet-standalone runtime in

doca-container-deployment.

The skill uses the same kind: tool three-file shape as the

rest of the bundle so the agent's task-verb contract

(configure / build / modify / run / test / debug) is uniform

across libraries, services, and tools.

When to load this skill

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

the DOCA Socket Relay on a real host or BlueField Arm with DOCA

installed (or inside the public NGC DOCA container with the right

device passthrough). Concretely:

• Migrating a socket-based application off a same-host peer onto

a BlueField-side terminator without rewriting the application.

• Picking the relay's deployment shape (in-process beside the app,

sidecar process / container, or a service container on the

BlueField) for a specific environment.

• Configuring the host-side socket the relay binds and the DPU-side

forwarding endpoint the relay points at, before any application

client tries to connect.

• Walking the bind → connect → round-trip → admit-fleet loop on a

brand-new relay deployment.

• Diagnosing a *"host app cannot connect"*, *"connection accepted

but no bytes flow"*, or *"first round-trip works, the rest hang"*

symptom against the relay's layered error surface.

• Cross-checking the relay's view against the host application

side and the DPU-side terminator when the three appear to

disagree.

Do not load this skill for general DOCA orientation, the comch

programming API, RDMA programming, line-rate raw packet I/O, or

DOCA install. For those, route to

doca-public-knowledge-map,

doca-comch,

doca-eth, or

doca-setup.

What this skill provides

This is a thin loader. Substantive material lives in two

companion files:

• CAPABILITIES.md — what the Socket Relay carries and changes:

the three-axis configuration model (deployment shape × socket

type / protocol × forwarding endpoint), the read-only vs

state-changing operation split, the version-availability overlay

that redirects to doca-version,

the layered error taxonomy (tool-not-installed / relay-not-bound

/ host-app-not-connecting / DPU-side-terminator-not-reachable /

permission / version / cross-cutting), the relay's role as the

data-plane counterpart to

doca-comch, and the

high-stakes safety policy that makes a misconfigured forwarding

endpoint a silent data-path break.

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

configure (the three-axis decision + the precondition probe),

build (route to install — the relay is shipped pre-built),

modify (refuse — modify the *invocation / deployment*, not the

binary), run (the bind → connect → round-trip flow), test

(the smoke-before-bulk eval loop), debug (the layered

diagnosis ladder), plus a Deferred task verbs block and a

Command appendix that honors the bundle's

doca-structured-tools-contract

preamble.

The skill assumes a host or BlueField where DOCA is already

installed (or the public NGC DOCA container is running with the

right device passthrough) and the operator has whatever privileges

the public DOCA Socket Relay guide requires for the chosen

deployment shape.

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 binary names, flag inventories, subcommand names,

socket-path defaults, port numbers, or output column names.**

The public DOCA Socket Relay guide on docs.nvidia.com and the

installed --help on the user's version are the joint source

of truth; copying them here pins the skill to one release and

silently rots when the relay evolves. The skill routes the agent

at those sources instead.

• Pre-baked example output. Output is install-, version-, and

deployment-specific. A captured example will mislead an operator

on a different platform / state.

• Wrappers, parsers, or scripts in any language that consume

the relay's output. The output format is documented; users who

want to script against it should read the live guide and write

the parser against their installed version.

• A samples/ or reference/ subtree. This is a thin loader

for a documented DOCA artifact; substantive material lives on

the public page and in --help.

Loading order

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

scope (the user wants to bridge a socket-based application onto

the DPU without rewriting it onto the DOCA programming surface,

not learn the comch / eth / RDMA APIs).

• **For what the relay carries, the three-axis configuration

model, the read-only vs state-changing split, version

availability, the layered error surface, observability, and

safety posture, see CAPABILITIES.md.**

• **For the documented invocations and the smoke-before-bulk

workflow — configure, build, modify, run, test,

debug, plus the Command appendix — see

TASKS.md.**

Related skills

• doca-comch — the host ↔ DPU

control-plane primitive (PCIe-based message channel between a

host and a DPU process). The Socket Relay is the data-plane

counterpart for socket-oriented applications: comch is what an

application uses to *coordinate* across the host ↔ DPU boundary

programmatically; the relay is what an application uses to

*carry* socket-shaped bytes across that boundary without being

rewritten. Pair the two when an application owner is migrating

in stages — control plane first via comch, data plane via the

relay until a per-library rewrite is justified.

• doca-eth — the line-rate raw

packet I/O surface that sits *below* the socket level. The relay

presents a socket-shaped interface to the application and rides

the underlying DOCA fabric; doca-eth is the right answer when

the application can be rewritten to operate on packets directly

rather than sockets, and when the throughput / latency profile

the relay achieves is no longer sufficient.

• doca-container-deployment

— the BlueField service-runtime contract (kubelet standalone +

static-pod manifests + per-service config-file mount). Load this

alongside the present skill when the operator's chosen

deployment shape is a relay container running on the BlueField

rather than a host-side process; the runtime contract there owns

the pod-spec / image-pull / static-pod / liveness pieces, this

skill owns the relay-specific config.

• doca-comm-channel-admin

— the operator-side admin CLI for comch channels. The

list → inspect → decide pattern there is the same shape the

Socket Relay uses for its own state: read-only inspection first,

state-changing operations gated on a clean smoke. Both tools are

members of the same family and the same patterns apply.

• doca-public-knowledge-map

— routing to the public DOCA Socket Relay guide and the rest of

the public DOCA documentation set. The canonical URL is reached

via doca-public-knowledge-map ## DOCA tools.

• doca-version — canonical DOCA

version-handling rules. The ## Version compatibility section

in CAPABILITIES.md is a concise overlay

that redirects here for the body.

• doca-structured-tools-contract

— the bundle's detect → prefer → fall back → report contract for

structured helper tools. The Command appendix in

TASKS.md honors this contract.

• doca-setup — env preparation,

install verification, representor visibility checks, and the *I

have no install yet* path with the public NGC DOCA container.

This skill assumes its preconditions are satisfied.

• doca-debug — the cross-cutting

debug ladder. The Socket Relay slots in at the *runtime* layer

as a data-path bridge whose layered error surface escalates to

the cross-cutting ladder when the cause is below DOCA.