Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iroh.computer/llms.txt

Use this file to discover all available pages before exploring further.

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 
cargo add iroh-services

​
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: 
export IROH_SERVICES_API_SECRET=<your-api-key>

​
3. Connect to iroh services and Grant Capability

Here’s a minimal integration: 
use anyhow::Result;
use iroh::{Endpoint, protocol::Router};
use iroh_services::{
    ApiSecret, Client, ClientHost, CLIENT_HOST_ALPN, API_SECRET_ENV_VAR_NAME,
    caps::NetDiagnosticsCap,
};

async fn setup_net_diagnostics(endpoint: &Endpoint) -> Result<Router> {
    // Get your secret somehow, either from an environment variable or config file
    let secret = ApiSecret::from_env_var(API_SECRET_ENV_VAR_NAME)?;

    // The remote_id is the id of the endpoint we'll be sending the network
    // report to, derived from the secret's address
    let remote_id = secret.addr().id;

    // Build the client
    let client = Client::builder(endpoint)
        .api_secret(secret)?
        .build()
        .await?;

    // Grant the GetAny capability so the platform can request diagnostics
    // from this endpoint on demand
    let client2 = client.clone();
    tokio::spawn(async move {
        client2
            .grant_capability(remote_id, vec![NetDiagnosticsCap::GetAny])
            .await
            .unwrap();
    });

    // Set up a ClientHost so the platform can dial back into this endpoint
    let host = ClientHost::new(endpoint);
    let router = Router::builder(endpoint.clone())
        .accept(CLIENT_HOST_ALPN, host)
        .spawn();

    Ok(router)
}

​
Understanding Reports

​
NAT Types

NAT TypeWhat it meansConnection quality
No NATLocal address matches public addressDirect connections work with correct firewall config
Endpoint-IndependentOne outbound UDP packet opens a port for any senderNAT traversal works reliably
Endpoint-DependentOnly the specific destination can reply (symmetric NAT)Connections will primarily use relays
UnknownNAT behavior could not be determinedCheck UDP connectivity

​
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.