Aspire.Hosting.DevTunnels 17.0.0

Prefix Reserved
dotnet add package Aspire.Hosting.DevTunnels --version 17.0.0
                    
NuGet\Install-Package Aspire.Hosting.DevTunnels -Version 17.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Aspire.Hosting.DevTunnels" Version="17.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Aspire.Hosting.DevTunnels" Version="17.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Aspire.Hosting.DevTunnels" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Aspire.Hosting.DevTunnels --version 17.0.0
                    
#r "nuget: Aspire.Hosting.DevTunnels, 17.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Aspire.Hosting.DevTunnels@17.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Aspire.Hosting.DevTunnels&version=17.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Aspire.Hosting.DevTunnels&version=17.0.0
                    
Install as a Cake Tool

Dev tunnels hosting integration

Provides extension methods and resource definitions for an Aspire AppHost to expose local application endpoints publicly via a secure dev tunnel.
Dev tunnels are useful for:

  • Sharing a running local service (e.g., a Web API) with teammates, mobile devices, or webhooks.
  • Testing incoming callbacks from external SaaS systems (GitHub / Stripe / etc.) without deploying.
  • Quickly publishing a temporary, TLS‑terminated endpoint during development.

By default tunnels require authentication and are available only to the user who created them. You can selectively enable anonymous (public) access per tunnel or per individual port.


Getting started

Add the integration

From your AppHost directory, add the Aspire.Hosting.DevTunnels integration with the Aspire CLI:

aspire add Aspire.Hosting.DevTunnels
aspire add Aspire.Hosting.Dotnet

Install the devtunnel CLI

Before you create a dev tunnel, you first need to download and install the devtunnel CLI (Command Line Interface) tool that corresponds to your operating system. See the devtunnel CLI installation documentation for more details.


Basic usage

Expose all endpoints on a project

C#

var builder = DistributedApplication.CreateBuilder(args);

var web = builder.AddDotnetProject("web", "../WebApp/WebApp.csproj");

var tunnel = builder.AddDevTunnel("mytunnel")
                    .WithReference(web);

builder.Build().Run();

TypeScript

import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const web = await builder.addNodeApp("web", "../web", "server.js");

const tunnel = await builder.addDevTunnel("mytunnel")
                    .withReference(web);

await builder.build().run();

Enable anonymous (public) access

var tunnel = builder.AddDevTunnel("publicapi")
                    .WithReference(web)
                    .WithAnonymousAccess();   // Entire tunnel (all ports) can be accessed anonymously

Expose only specific endpoint(s)

var web = builder.AddDotnetProject("web", "../WebApp/WebApp.csproj");

var tunnel = builder.AddDevTunnel("apitunnel")
                    .WithReference(web.GetEndpoint("api"));  // Only expose the "api" endpoint

Per‑port anonymous access

You can control anonymous access at the port (endpoint) level using the overload of WithReference that accepts a bool allowAnonymous parameter:

var api = builder.AddDotnetProject("api", "../Api/Api.csproj");

var tunnel = builder.AddDevTunnel("mixedaccess")
                    .WithReference(api.GetEndpoint("public"), allowAnonymous: true)
                    .WithReference(api.GetEndpoint("admin"));  // This endpoint requires authentication

Custom tunnel ID, description, and labels

var options = new DevTunnelOptions
{
    Description = "Shared QA validation tunnel",
    Labels = { "qa", "validation" },
    AllowAnonymous = false
};

var tunnel = builder.AddDevTunnel(
                 name: "qa",
                 tunnelId: "qa-shared",
                 options: options)
             .WithReference(api);

Setting devtunnel region

When creating a dev tunnel, you can optionally specify the Azure region where the tunnel will be hosted. If not set, when attempting to connect to an existing dev tunnel, it is possible based on ping a different region is chosen. This will create a new dev tunnel in that region, which may be undesired if testing registered webhooks or a similar scenario.

To prevent this behaviour, it is recommended to explicitly set the desired region.

var options = new DevTunnelOptions
{
    Region = DevTunnelRegion.NorthEurope
};

var tunnel = builder.AddDevTunnel(name: "devtunnel", options: options)            
                    .WithReference(api);
             

Configure idle expiration

Set an idle expiration period to clean up tunnels that are no longer used:

C#

var tunnel = builder.AddDevTunnel("mytunnel")
                    .WithExpiration(24)
                    .WithReference(web);

Alternatively, set ExpirationHours on DevTunnelOptions when calling AddDevTunnel.

TypeScript

const tunnel = await builder.addDevTunnel("mytunnel")
                    .withExpiration(24)
                    .withTunnelReferenceAll(web, false);

Expiration is expressed as a whole number of hours, from one hour through 30 days, inclusive. The setting applies to both new tunnels and existing tunnels reused by the AppHost. If omitted, new tunnels use the service default and existing tunnels keep their configured expiration period.

This is the time a tunnel can remain unused or unmodified before it expires, not a limit on hosting duration or an access-token lifetime. See the devtunnel CLI expiration documentation.

Multiple tunnels for different audiences

var web = builder.AddDotnetProject("web", "../WebApp/WebApp.csproj");

var publicTunnel = builder.AddDevTunnel("public")
                          .WithReference(web)
                          .WithAnonymousAccess();

var privateTunnel = builder.AddDevTunnel("private")
                           .WithReference(web);  // Requires authentication

Service discovery integration

When another resource references a dev tunnel via:

builder.AddDotnetProject("client", "../ClientApp/ClientApp.csproj")
       .WithReference(web, publicTunnel);  // Use the tunneled address for 'web'

Environment variables are injected after the tunnel port is allocated using the Aspire service discovery configuration format:

services__{ResourceName}__{EndpointName}__0 = https://{public-host}/

Example:

services__web__https__0 = https://myweb-1234.westeurope.devtunnels.ms/

This lets downstream resources use the tunneled address exactly like any other Aspire service discovery entry. Note that dev tunnels are a development time concern only and are not included when publishing or deploying an Aspire AppHost, including any service discovery information.

Referencing a tunnel delays the consumer resource's start until the tunnel has started and its endpoint is fully allocated.


Anonymous access options

Scope How to enable Notes
Entire tunnel tunnel.WithAnonymousAccess() Affects all ports unless overridden at port level.
Specific port(s) WithReference(endpoint, allowAnonymous: true) Fine-grained control per exposed endpoint.

If neither is set, the tunnel is private and authentication as the tunnel creator is required.


Protocol handling

DevTunnelPortOptions.Protocol supports:

  • http
  • https
  • auto (let the service decide)
  • null (default = use the referenced endpoint's scheme)

Unsupported schemes (e.g., non-HTTP(S)) will throw an exception.


Tunnel logging and diagnostics

When dev tunnel ports are successfully allocated, they log detailed information about their forwarding configuration and access level. This helps you understand which URLs are available and their security settings.

Connection status and compatibility

Aspire observes the devtunnel host console output to make public endpoints available as soon as the local host reports that it is ready. Connection loss updates the tunnel and port resources without waiting for the next health check. Links remain inactive if delayed URL callbacks complete after the tunnel stops. A running CLI process does not necessarily mean its tunnel connection is active.

Health checks also reconcile tunnel ports and access settings with the dev tunnels service. If port or readiness output is unrecognized, Aspire logs a warning and uses service-based reconciliation to discover the endpoints once this local host has reported a connection. A remote host count alone cannot establish local readiness: another machine might be hosting the same tunnel. If no local connection message is recognized, the tunnel remains unready rather than exposing another host's endpoints. Minor whitespace, line wrapping, and separator differences are supported. The warning is limited to once per resource start; the original console output remains available in the tunnel resource's logs.

Starting a tunnel checks its remote configuration and reuses matching tunnels and ports. Unchanged access policies are left intact; changed policies are reconciled before hosting. Ports are recreated only when their protocol, description, or labels differ from the application model. Remote drift is checked on each start rather than relying on a cached successful setup.

For ports configured with allowAnonymous: false, an existing permanent, non-inverse anonymous connection deny is retained even if additional access rules are present. An expiring deny is not a permanent restriction, and inverse anonymous rules apply to authenticated users rather than anonymous callers. If a permanent deny is missing, it is added without first clearing the other rules. This avoids temporarily removing an existing restriction during in-place reconciliation.

If tunnel status is incorrect after such a warning, include the output of devtunnel --version and the relevant tunnel console logs in an Aspire issue, after removing sensitive information. A service response indicating an active host will not override a disconnect reported by the local CLI or reactivate a connection whose loss or tunnel deletion was established by reconciliation, because that connection may belong to another host. Initial service-status propagation is tracked separately from the loss of a previously confirmed connection.

Port forwarding logs

Each port resource logs its forwarding configuration when it becomes available:

Forwarding from https://37tql9l1-7023.usw2.devtunnels.ms to https://localhost:7023/ (webfrontend/https)

Anonymous access logging

Port resources also log their effective anonymous access policy when first known or when it changes, showing both the current access level and the configuration that led to it. The display ignores inverse rules and expired entries. A failed policy query clears that port's access property instead of retaining a stale value; successful policy queries for other ports are still applied. Access metadata refreshes do not block subsequent tunnel/port status checks.

When anonymous access is allowed:

!! Anonymous access is allowed (port explicitly allows it) !!
!! Anonymous access is allowed (inherited from tunnel) !!

When anonymous access is denied:

Anonymous access is not allowed (tunnel does not allow it and port does not explicitly allow or deny it)
Anonymous access is not allowed (tunnel allows it but port explicitly denies it)

The logging helps you verify that your tunnel configuration is working as expected and troubleshoot access issues.


Security considerations

  • Prefer authenticated tunnels during normal development.
  • Only enable anonymous access for endpoints that are safe to expose publicly.
  • Treat public tunnel URLs as temporary & untrusted (rate limit / validate input server-side).

Additional documentation


Feedback & contributing

https://github.com/microsoft/aspire

Contributions (improvements, clarifications, samples) are welcome.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Aspire.Hosting.DevTunnels:

Package Downloads
Aspire.Hosting.Maui

MAUI integration for Aspire (local dev only)

KubeOps.Aspire.Hosting

.NET Aspire hosting integration for KubeOps operators. Adds an AddKubeOps extension to the distributed application builder so a KubeOps operator project can be orchestrated as a resource in a .NET Aspire AppHost, wired up with references, environment variables and telemetry.

GitHub repositories (3)

Showing the top 3 popular GitHub repositories that depend on Aspire.Hosting.DevTunnels:

Repository Stars
dotnet/maui-samples
Samples for .NET Multi-Platform App UI (.NET MAUI)
bitfoundation/bitplatform
Build all of your apps using what you already know and love ❤️
swdriessen/starlights
A work-in-progress project intended as an online toolset to enhance tabletop role‑playing games. “Aurora Online”
Version Downloads Last Updated
17.0.0 2,663 11/18/2026
13.6.5 30,013 11/10/2026
13.6.4 20,199 10/24/2026
13.6.3 5,702 10/21/2026
13.6.2 2,971 10/20/2026
13.6.1 51,558 10/7/2026
13.6.0 17,538 9/29/2026
13.5.4 57,940 9/15/2026
13.5.3 38,061 8/25/2026
13.5.2 7,750 8/21/2026
13.5.1 2,515 8/20/2026
13.5.0 7,425 8/18/2026
13.4.6 95,391 6/19/2026
13.4.5 5,584 6/17/2026
13.4.4 6,931 6/15/2026
13.4.3 12,052 6/8/2026
13.4.2 92,727 6/3/2026
13.4.1 819 6/3/2026
13.4.0 9,117 6/1/2026
13.3.5 19,379 5/21/2026
Loading failed