Skip to content
Dynamo Router Starter

Dynamo Router Starter Skill

NVIDIA's official skill for bringing up Dynamo inference routing — pick a router mode, enable KV-aware routing, and smoke-test the frontend endpoint before claiming anything works.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from NVIDIA/skills.

$ npx skills add NVIDIA/skills --skill dynamo-router-starter

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/dynamo-router-starter/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/NVIDIA/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/dynamo-router-starter ~/.claude/skills/dynamo-router-starter

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/dynamo-router-starter/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Bring-up for round-robin, KV-aware, least-loaded, device-aware and direct router modes
  • Kubernetes env patch (DYN_ROUTER_MODE) instead of rewriting the deployment recipe
  • Detects missing worker KV events and falls back to approximate mode explicitly
  • check_router_health.py smoke test over /v1/models and one chat completion
  • Refuses to report throughput gains from a smoke test — benchmarks are a separate skill
  • Symptom-to-cause troubleshooting table for empty model lists, hangs and dropped port-forwards

NVIDIA Dynamo distributes inference across a fleet of workers, and its router mode is the setting that decides whether that fleet is actually being used well. Round-robin is the safe baseline; KV-aware routing sends a request to the worker most likely to already hold its prefix in cache; least-loaded and device-aware weighted trade differently again. This skill from NVIDIA's verified skills catalogue gets an agent from nothing to a working, proven routing setup.

It covers both deployment shapes. Locally, that is python3 -m dynamo.frontend --router-mode ... on a chosen HTTP port. On Kubernetes, it patches only the frontend service's environment — DYN_ROUTER_MODE — rather than rewriting a recipe, and it knows the specific trap that catches people: if the backend workers are not publishing KV cache events, KV mode will sit and wait, so the skill sets DYN_ROUTER_USE_KV_EVENTS=false for approximate mode and tells you it has done so.

The part worth having is the discipline around results. Every bring-up ends with check_router_health.py, which verifies /v1/models and issues one real chat completion. The skill then explicitly forbids drawing a throughput conclusion from that single request: mode comparisons must hold model, workers, prompt set, concurrency and sampling constant, repeated-prefix prompts are required to demonstrate KV reuse, and anything short of a proper benchmark run must be labelled a smoke comparison. It also ships a symptom-to-cause troubleshooting table — empty /v1/models, hanging KV mode, dropped port-forwards — and hands off to dynamo-troubleshoot when the endpoint is genuinely unhealthy.

Every skill in NVIDIA's catalogue ships with a verifiable NVIDIA signature (skill.oms.sig), governance metadata, and an auto-generated benchmark report. Needs Python 3.10+ with the dynamo package, and kubectl access for Kubernetes runs.

Try it

Once installed, ask your agent something like:

"Switch our Dynamo frontend on the dynamo-demo namespace to KV-aware routing and prove the endpoint still serves a chat completion."

SKILL.md

The instructions your agent loads, as published by NVIDIA.

SKILL.md
name
dynamo-router-starter
description
Start or patch Dynamo router modes and run router endpoint smoke checks. Use for round-robin, KV-aware, least-loaded, or device-aware routing setup; use recipe-runner for recipe deployment and troubleshoot for failure diagnosis.
license
Apache-2.0
metadata
author: Dan Gil <dagil@nvidia.com> tags: - dynamo - router - smoke-test - bring-up

Dynamo Router Starter

<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: CC-BY-4.0
-->

Purpose

Make Dynamo routing feel easy by getting a baseline router mode running, enabling
KV-aware routing when appropriate, and proving the endpoint works. Keep the user
focused on exact commands and success signals, not router internals.

Prerequisites
  • Python 3.10+ with the dynamo package importable (python3 -m dynamo.frontend --help works).
  • For Kubernetes runs: kubectl configured with access to the target namespace and a deployed Dynamo recipe.
  • Network reachability to the frontend service (port-forward or direct).
  • A model already loaded into at least one worker (/v1/models returns at least one entry).
Required Inputs

Collect or infer:

  • local Python/CLI or Kubernetes recipe path
  • desired mode: round-robin, kv, least-loaded, device-aware-weighted, direct, or random
  • frontend port or Kubernetes frontend service
  • whether workers publish KV events; if not, use approximate KV mode
  • model name for smoke requests, if /v1/models cannot discover it
Instructions
1. Establish A Baseline

For local bring-up with already registered workers:

python3 -m dynamo.frontend --router-mode round-robin --http-port 8000

For Kubernetes, inspect the selected recipe deploy.yaml and locate the
frontend service. If the recipe is not already deployed, use
dynamo-recipe-runner first.

2. Enable KV Routing

For local frontend:

python3 -m dynamo.frontend --router-mode kv --http-port 8000

For Kubernetes, patch only the frontend service env:

envs:
  - name: DYN_ROUTER_MODE
    value: kv

If backend workers are not publishing KV cache events, set approximate mode
instead of leaving the router waiting for events:

envs:
  - name: DYN_ROUTER_USE_KV_EVENTS
    value: "false"
3. Smoke Test

After port-forwarding the frontend service or starting local frontend, run:

python3 scripts/check_router_health.py \
  --base-url http://127.0.0.1:8000

This must verify /v1/models and, when a model is discoverable, one
/v1/chat/completions request.

4. Compare Modes Carefully

When comparing round-robin vs KV routing:

  • use the same model, workers, prompt set, concurrency, and sampling settings
  • send repeated-prefix prompts if demonstrating KV reuse
  • label the result as a smoke comparison unless enough benchmark samples were collected
  • do not claim throughput improvement from a single chat request

If the endpoint is unhealthy or workers are missing, switch to
dynamo-troubleshoot.

Available Scripts
ScriptPurposeArguments
scripts/check_router_health.pySmoke-test /v1/models and one chat completion against a Dynamo frontend--base-url, --retries, --timeout

Invoke via the agentskills.io run_script() protocol:

run_script("scripts/check_router_health.py", args=["--base-url", "http://127.0.0.1:8000"])
Examples

Local KV-routed frontend on port 8000, then smoke-test it:

python3 -m dynamo.frontend --router-mode kv --http-port 8000 &
python3 scripts/check_router_health.py --base-url http://127.0.0.1:8000

Kubernetes-deployed frontend reachable via port-forward:

kubectl port-forward svc/qwen-vllm-disagg-frontend 8000:8000 -n dynamo-demo &
python3 scripts/check_router_health.py --base-url http://127.0.0.1:8000 --retries 3

Equivalent through the agent protocol:

run_script("scripts/check_router_health.py", args=["--base-url", "http://127.0.0.1:8000", "--retries", "3"])
Output Contract

Return:

  • mode selected and why
  • local command or Kubernetes env patch
  • frontend service or URL
  • smoke-test result
  • any limitation, such as approximate KV mode or missing worker KV events
  • next command to run for a fuller comparison
Limitations
  • Smoke test is one chat completion; it is not a benchmark. Use dynamo-benchmark for throughput/latency numbers.
  • KV-aware mode without worker KV-event publication degrades to approximate mode; this skill flags but does not fix the underlying worker config.
  • Mode comparisons require matched workloads; cross-mode latency claims need separate benchmark runs.
Troubleshooting
SymptomLikely causeNext step
/v1/models returns empty listNo worker registered with the frontendVerify worker pods are Ready; confirm they connect to the same etcd/NATS
Smoke chat request times outFrontend up, workers not servingSwitch to dynamo-troubleshoot; inspect worker logs
KV mode hangsWorkers do not publish KV cache eventsSet DYN_ROUTER_USE_KV_EVENTS=false (approximate mode)
Connection refused on port-forwardPort-forward dropped or wrong service nameRe-run port-forward; verify the frontend service name matches the recipe
Benchmark

See BENCHMARK.md for the NVCARPS-EVAL performance report (auto-generated by the NVSkills CI pipeline). To refresh, re-run /nvskills-ci on an upstream PR touching this skill.

References
  • Read references/router-modes.md for the compact mode/env map.
  • Use scripts/check_router_health.py for endpoint smoke tests.
Install

Trains, distils, quantises, evaluates, exports and runs inference for RT-DETR real-time object detection in NVIDIA TAO, routing training through AutoML hyperparameter search by default.

Browse all skills →