AutoGineer
Generated banner for Dynamo Router Starter
Generated logo for Dynamo Router Starter

Dynamo Router Starter

OpenAIOfficialCreated by Dan GilDistributed by OpenAI

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
  • Has scripts
Download ZIP

From the author

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.
— the description by Dan Gil

AutoGineer summary

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

Dynamo Router Starter provides a standardized procedure for initializing and patching Dynamo router configurations. It supports multiple routing strategies including round-robin, KV-aware, and least-loaded modes. The skill includes instructions for both local Python-based setups and Kubernetes deployments, ensuring that the frontend is correctly configured and that backend workers are properly registered. It also provides a health check script to verify model discovery and basic chat completion functionality, helping users transition from initial bring-up to functional validation.

What it does

  • Configures Dynamo frontend router modes via CLI or Kubernetes environment variables.
  • Supports various routing strategies like round-robin, KV-aware, and least-loaded.
  • Provides a smoke test script to verify model availability and chat completion endpoints.
  • Offers guidance on enabling approximate KV mode when worker events are unavailable.
  • Facilitates the transition from initial setup to troubleshooting if endpoints fail.
  • Standardizes the validation process for Dynamo router deployments.

When to use it

  • When setting up a new Dynamo router instance locally or in Kubernetes.
  • When switching between different routing modes to optimize traffic distribution.
  • When verifying that a deployed Dynamo frontend is correctly communicating with backend workers.
  • When performing initial smoke tests before running full-scale performance benchmarks.

Advantages

  • Simplifies complex router configuration by providing clear CLI and YAML patterns.
  • Ensures consistent validation through automated health check scripts.
  • Helps identify common configuration issues like missing worker registrations or KV event mismatches.
  • Provides a clear path for troubleshooting when endpoints are unhealthy.

Usage examples

“Start a local Dynamo frontend in KV-aware mode on port 8000 and verify it.”
The agent executes the frontend command with the appropriate flags and runs the health check script to confirm the endpoint is operational.
“How do I configure my Kubernetes Dynamo frontend for KV routing?”
The agent provides the necessary environment variable patches for the frontend service, including the option to toggle approximate KV mode.
“Run a smoke test on my Dynamo router at http://127.0.0.1:8000.”
The agent invokes the health check script against the specified URL to verify model discovery and chat completion success.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/openai/dynamo-router-starter/download

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

    mkdir -p .agents/skills && unzip dynamo-router-starter.zip -d .agents/skills

Documentation by Dan Gil

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.

Files

skill.oms.sig

{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{"x509CertificateChain":{"certificates":[{"rawBytes":"MIICgzCCAgmgAwIBAgIUKIyS7SxNteQIiWzK1dWj85E6520wCgYIKoZIzj0EAwMwVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwHhcNMjYwNDAxMDAwMDAwWhcNMjgwNDIyMTUzMzA5WjBUMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTlZJRElBIENvcnBvcmF0aW9uMSgwJgYDVQQDDB9OVklESUEgQWdlbnQgU2tpbGxzIFNpZ25pbmcgMDAxMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEYoRM9bQl/dGlwSRNi6bTpIJUXH8Nv9GciP6LSflJYYMLCc296kpyuTSsk5ddbAWiDcFX3C/ydX3jwc+qCLYP6uHy9XphyLjOQ27Yb2J6rBLVtRBS1mgGco/Gr7fL6ODco4GaMIGXMB0GA1UdDgQWBBRQ/5ZW3nJ6lmo9SVk7I15o7UGmpTAfBgNVHSMEGDAWgBRPGpILxMBBleJSsBGjrMKsby1CgjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUHMAGGG2h0dHA6Ly9vY3NwLm5kaXMubnZpZGlhLmNvbTAKBggqhkjOPQQDAwNoADBlAjAUygu/GiOCIXrgGr4SmLgeEVDcEitfFUv7ALbvLVGVyMysB3mxmO/uInZfXzWcJZsCMQDxuoxj4ZmO30jhkPIcCxGFCOvnUsnfU3TfGcouYm4M6iRpbKvtVnHPiy4bi6pcKf0="},{"rawBytes":"MIICiDCCAg6gAwIBAgIUZsIuSv9NkpJCNqtYEfCouVv5BzowCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAASI72cR3ctKGg4VWnB3bNja6g1Z2PnOmFEopkPof+QeIcPk9rT+g9MjJnq51EQXL93a7C2GJ9J985G4o2V85VD7wJ1RaXhluHW2rf3y8bQGeAYaKMr5s/hUgn+M3/9WlWejgaAwgZ0wHQYDVR0OBBYEFE8akgvEwEGV4lKwEaOswqxvLUKCMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AubmRpcy5udmlkaWEuY29tMAoGCCqGSM49BAMDA2gAMGUCMQCeIMMfAbyzPDacw2MxG+Yt1cikrJX/DVxiGfXuHmkkXn6VgSzE79+lkqDErpVO2gYCMCNEColOyvUvkzZGUEI1hQ3PfMgi3FIo9tHoBKMw4/wGBLFpu/0ubtmbBXM6/UMOEw=="},{"rawBytes":"MIICRTCCAcygAwIBAgIUeJdY3rV86EdvFmG7L8LJBsyQFYkwCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABAYpiXCDjJ9NT2eSDhyHJVSw1Tbze18cGG2F/578oWvHxg23eQAhNRYdq88i1iOshZSO6C29doKui5Xpmo/7Ctw9Sx4PP2RzOmIuOLCuTdNtKcTRwi4GEsd5BAFvWj42M6NjMGEwHQYDVR0OBBYEFItnoAjjfuCEUvzyvWyI2vOGvwPjMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2cAMGQCMCwtAjWLaNwgGWNCgdyNoTyvNhqWRECRJV2r3+7w8g0PL6NHLOsbkgE09BH95h8XlgIwTaQmbbUh2ChAJ5TA1wRiVDnCcvbzHlZl2jM2FcwQQZlk19LOAbyGMRixbu2Ww/rj"}]},"tlogEntries":[]},"dsseEnvelope":{"payload":"ewogICJfdHlwZSI6ICJodHRwczovL2luLXRvdG8uaW8vU3RhdGVtZW50L3YxIiwKICAic3ViamVjdCI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAiZHluYW1vLXJvdXRlci1zdGFydGVyIiwKICAgICAgImRpZ2VzdCI6IHsKICAgICAgICAic2hhMjU2IjogIjAxZDM1M2I1MDBkYTI4NmE0ZWI5N2IyMDRiYjZkZTEwODcxOTQwNDQ4ZjU5OGYzZWZmY2UzODE5ZGEwMGQ5NzIiCiAgICAgIH0KICAgIH0KICBdLAogICJwcmVkaWNhdGVUeXBlIjogImh0dHBzOi8vbW9kZWxfc2lnbmluZy9zaWduYXR1cmUvdjEuMCIsCiAgInByZWRpY2F0ZSI6IHsKICAgICJzZXJpYWxpemF0aW9uIjogewogICAgICAiaWdub3JlX3BhdGhzIjogWwogICAgICAgICIuZ2l0aWdub3JlIiwKICAgICAgICAiLmdpdGh1YiIsCiAgICAgICAgIi5naXRhdHRyaWJ1dGVzIiwKICAgICAgICAiLmdpdCIKICAgICAgXSwKICAgICAgImhhc2hfdHlwZSI6ICJzaGEyNTYiLAogICAgICAibWV0aG9kIjogImZpbGVzIiwKICAgICAgImFsbG93X3N5bWxpbmtzIjogZmFsc2UKICAgIH0sCiAgICAicmVzb3VyY2VzIjogWwogICAgICB7CiAgICAgICAgImRpZ2VzdCI6ICI4NzY2ZTRkZTRmZTNjOGVjYWNlZTg5ZDk2MWVmZmYyZTQzNTc0YzY2NDBmNjc4NGVhZDJkZTFhNzUyYzNjN2NiIiwKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgIm5hbWUiOiAiQkVOQ0hNQVJLLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImRpZ2VzdCI6ICIxMjc0YTQ3YmNkMjhjNTA4NmMyNmNlMWExMGYyYjJlNmM0YTI4YjFiM2ZhOTU5OWFkMmM0ZDFjYjZiYTY3NzI4IiwKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgIm5hbWUiOiAiU0tJTEwubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiZGlnZXN0IjogIjMyZTdmMWI2NTBlMTU5OWE2YjY4NDY4YWRiMmNjMjdlYzY5YWVhMWNmNzVkOTRjNjY2NTg4ZjI2MWI3MmM2ZGMiLAogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJldmFscy9ldmFscy5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImRpZ2VzdCI6ICIyMTI2ZGUyYTYzN2ZiMzhjY2NmNzczMzNlMDNmNzMwN2UxMjhhNGY3YjA4OGE0MmQwY2MzOWI5M2U4MzQwNmYzIiwKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9yb3V0ZXItbW9kZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiZGlnZXN0IjogIjcyMzIxZjQ0Mjc0NjFiZmJhNDk3MjI3ZDFlNTU0YzJmZjgzZWZiYzM5ZDRlZDNmMzZmMmM3NWM4NDA0MTBkZTIiLAogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJzY3JpcHRzL2NoZWNrX3JvdXRlcl9oZWFsdGgucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiZGlnZXN0IjogIjVjNjQ2ZGI5MGU0NjViMTYxODk4ZTg3MDUzOTc1MGQyZDEwZWQ1YmQ3MTBlNWQwZWY3MDUxZjBlNDk0ZGZkMmQiLAogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJza2lsbC1jYXJkLm1kIgogICAgICB9CiAgICBdCiAgfQp9","payloadType":"application/vnd.in-toto+json","signatures":[{"sig":"MGUCMQCQDxyydCBcTxvLDX+m29S4jFD0OOk0y2txWFZUF1x3a2KsakEDToUcd24Mq68hqrQCMBd0HF9bR5bxH/YoT0ZbbE4ylAofjLRWe1+z6w1l7tXJXD3wkG+vblB2wdYtS6a7yg==","keyid":""}]}}

Requirements and compatibility

Written for: OpenAI Codex

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.

Needs: Needs a command-line tool, Needs Python

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

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
Dan Gil
Publisher
OpenAI (Official)
Distributed by
OpenAI
Source
openai/plugins · plugins/nvidia/skills/dynamo-router-starter · commit d420d13
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (written by AutoGineer)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Also distributed in
NVIDIA/skills

AutoGineer is not affiliated with or endorsed by Dan Gil or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download dynamo-router-starter.zip