Skip to main content
When you click Run Diagnostics in the dashboard, the platform dials back into your endpoint using the capability token your app granted. Your ClientHost receives the request, runs the diagnostics locally (probing UDP connectivity, NAT behavior, relay latency, and port mapping), and returns the report to iroh services for display.

Integrating Net Diagnostics Into Your App

To add net diagnostics support to your own iroh application, you need to:
  1. Connect to iroh services with an iroh_services::Client
  2. Grant the NetDiagnosticsCap::GetAny capability to iroh services so it can request diagnostics from your endpoint
  3. Run a ClientHost so iroh services can dial back into your endpoint
See the net_diagnostics example in the iroh-services repository for a complete working example of this integration.

1. Update Cargo.toml

Add the dependency

2. Get Your API Key

Create one from your project’s Settings → API Keys tab. See API Keys for the full walkthrough. Then export it as an environment variable:

3. Connect to iroh services and Grant Capability

Here’s a minimal integration:

Understanding Reports

NAT Types

Connectivity Summary

The report includes a color-coded connectivity summary:
  • Green: UDP works and NAT is favorable. Direct connections should work.
  • Orange: Endpoint-Dependent NAT. Direct connections may be difficult; traffic will often be relayed.
  • Red: No UDP connectivity. Traffic will be relayed.

Troubleshooting

The capability grant (NetDiagnosticsCap::GetAny) authorizes the platform to request diagnostics from your endpoint. Without this grant, the Run Diagnostics button will be disabled in the dashboard even if the endpoint is online.