How to Get Support for Switchyard: Official Channels and Best Practices

Switchyard provides official support through GitHub Issues for bug reports and feature requests, comprehensive documentation for self-service troubleshooting, and a dedicated NVIDIA PSIRT channel for security vulnerabilities.

Switchyard, NVIDIA's open-source LLM routing and proxy framework, offers multiple pathways for users to obtain help, report issues, and contribute improvements. Whether you are deploying the standalone server or embedding the Python library, knowing how to get support for Switchyard ensures rapid resolution of configuration errors, routing bugs, or architectural questions. This guide covers the official channels, required diagnostic information, and essential source files referenced in the NVIDIA-NeMo/Switchyard repository.

Official Support Channels for Switchyard

GitHub Issues (Primary Channel)

The main repository uses GitHub Issues as the primary venue for bug reports, feature requests, and general troubleshooting. According to the Community section in README.md (lines 80-84), users should open a new issue at the repository’s issue tracker: https://github.com/NVIDIA-NeMo/Switchyard/issues. This channel enables community-driven troubleshooting and direct feedback from maintainers.

Documentation and Self-Service Resources

Before opening an issue, consult the comprehensive documentation included in the repository. Key files include:

• docs/architecture.md – Provides system architecture overviews for understanding proxy and library interactions
• docs/core_concepts.md – Explains fundamental routing concepts and algorithm behaviors
• docs/reference/toml_schema.md – Contains the complete TOML schema reference for routes.toml configuration validation
• crates/switchyard-server/README.md – Covers server-specific installation, build options, and runtime flags

Security Vulnerability Reporting

For confidential disclosure of security flaws, use the dedicated process outlined in SECURITY.md (lines 18-23). Submit vulnerabilities through the NVIDIA security form at https://www.nvidia.com/en-us/support/submit-security-vulnerability/ or email PSIRT directly at psirt@nvidia.com. This channel ensures sensitive information remains private while reaching the appropriate security team for coordinated disclosure.

Information to Include When Requesting Help

To expedite resolution, provide these details in your support request:

1. Switchyard version – Output from pip show nemo-switchyard or cargo install --list | grep switchyard
2. Operating system and runtime environment – OS name, Python or Rust versions, and deployment mode (standalone server versus embedded library)
3. Reproduction steps – Minimal script or command that triggers the issue consistently
4. Relevant configuration – Sanitized snippet of your routes.toml file without API keys or sensitive endpoints

Quick Diagnostics and Troubleshooting Examples

These commands and scripts help isolate issues before submitting a report.

Verifying Your Installation

# Python package version

pip show nemo-switchyard

# Rust binary version (if using the server)

switchyard-server --version

Testing the Embedded Library

# Save as demo.py

from switchyard.libsy import LlmResponse, Step
from switchyard.libsy.algorithms import stage_router

# Define a simple stage router between two dummy targets

algorithm = stage_router(
    capable="capable",
    efficient="efficient",
    picker="efficient_first",
    confidence_threshold=0.5,
)

# Dummy request – replace with a real request shape if needed

request = {
    "model": "switchyard",
    "messages": [{"role": "user", "content": "Hello"}],
}

# Simple in‑process driver (no actual model calls)

async def dummy_client(call):
    # Echo back the request for illustration

    return {"choices": [{"message": {"role": "assistant", "content": "Hi!"}}]}

async def run_demo():
    async for step in algorithm.run_stream(request):
        if isinstance(step, Step.CallModel):
            # Attach a fake response

            step.respond(LlmResponse.Agg(await dummy_client(step)))
        elif isinstance(step, Step.Done):
            print("Final response:", step.outcome.response)

import asyncio
asyncio.run(run_demo())

If the demo hangs or raises an exception, copy the traceback into your GitHub issue.

Testing the Standalone Proxy

# 1️⃣ Install the server

cargo install --locked switchyard-server

# 2️⃣ Create a simple routes.toml (see docs for the full schema)

cat > routes.toml <<'TOML'
schema_version = 1

[llm_clients.openrouter]
format = "openai_chat"
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"

[targets.capable]
id = "anthropic/claude-opus-4.8"
llm_client = "openrouter"

[targets.efficient]
id = "z-ai/glm-5.2"
llm_client = "openrouter"

[routes.switchyard]
type = "stage_router"
capable_target = "capable"
efficient_target = "efficient"
picker = "efficient_first"
confidence_threshold = 0.5
TOML

# 3️⃣ Run the server

export OPENROUTER_API_KEY="your-key"   # pragma: allowlist secret

switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

# 4️⃣ Send a test request

curl http://127.0.0.1:4000/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{"model":"switchyard","messages":[{"role":"user","content":"Hello"}]}'

Capture the full curl output if the request fails, and include it in your support ticket.

Key Source Files for Debugging

Understanding these files helps diagnose issues independently:

• README.md – Contains the Community section (lines 80-84) linking to GitHub Issues and quick-start guides
• SECURITY.md – Defines the confidential reporting process for vulnerabilities (lines 18-23)
• docs/architecture.md – Explains how the proxy, library, and translation layers interact
• docs/reference/toml_schema.md – Essential for resolving configuration syntax errors in routes.toml
• crates/switchyard-server/README.md – Server-specific deployment and runtime documentation
• switchyard/libsy/algorithms.py – Implements core routing algorithms including stage_router for debugging routing decisions

Summary

• GitHub Issues serve as the primary community-driven support channel for bugs and feature requests in the NVIDIA-NeMo/Switchyard repository
• Documentation in docs/ and README.md provides self-service resources for architecture and configuration questions
• Security vulnerabilities must be reported through NVIDIA's PSIRT form or email, not public GitHub Issues
• Always include version information, environment details, reproduction steps, and sanitized configuration when requesting help
• Reference switchyard/libsy/algorithms.py and docs/reference/toml_schema.md for deep troubleshooting of routing logic and TOML syntax

Frequently Asked Questions

Where do I report bugs or request features for Switchyard?

Open a GitHub Issue at the official repository issue tracker. The Community section in README.md (lines 80-84) directs users to https://github.com/NVIDIA-NeMo/Switchyard/issues for all bug reports, feature requests, and general questions. This allows maintainers and community members to track and resolve problems collaboratively.

How do I report a security vulnerability in Switchyard?

Use the dedicated security process defined in SECURITY.md (lines 18-23). Submit confidential reports through the NVIDIA security vulnerability form or email PSIRT at psirt@nvidia.com. Never disclose security issues in public GitHub Issues, as this could expose users to potential exploits before a patch is available.

What information should I include in a Switchyard support request?

Include your Switchyard version (via pip show nemo-switchyard or cargo install --list), operating system and runtime versions, minimal reproduction steps or scripts, and sanitized snippets of your routes.toml configuration. Providing these details aligns with the guidelines in SECURITY.md and helps maintainers reproduce issues quickly.

Can I get help with TOML configuration errors?

Yes. Consult docs/reference/toml_schema.md for the complete configuration schema, and check docs/architecture.md to understand how components interact. If documentation does not resolve your issue, open a GitHub Issue with the specific error message and a sanitized copy of your configuration file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}