Aspire dev tunnels integration (Preview)

Includes: Hosting integration only — Client integration not included

Dev tunnels allow developers to securely share local web services across the internet. The Aspire dev tunnels integration makes it easy to model dev tunnels in your AppHost projects so that they're automatically managed during development.

Dev tunnels are useful for:

• Sharing a running local service (for example, 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.

Prerequisites

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.

Hosting integration

To get started with the Aspire dev tunnels integration, install the 📦 Aspire.Hosting.DevTunnels NuGet package in the AppHost project.

dotnet add package Aspire.Hosting.DevTunnels --prerelease

<PackageReference Include="Aspire.Hosting.DevTunnels"
                  Version="*" />

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add a dev tunnel resource

In the AppHost project, add a dev tunnel and configure it to expose specific resources:

var builder = DistributedApplication.CreateBuilder(args);

var web = builder.AddProject<Projects.Web>("web");

builder.AddDevTunnel("tunnel")
       .WithReference(web);

builder.Build().Run();

When you run the AppHost, the dev tunnel is created to expose the web application endpoints publicly. The tunnel URLs are shown in the Aspire dashboard. By default, the tunnel requires authentication and is available only to the user who created it.

Allow anonymous access

To allow anonymous (public) access to the entire tunnel, chain a call to the WithAnonymousAccess method:

var builder = DistributedApplication.CreateBuilder(args);

var web = builder.AddProject<Projects.Web>("web");

builder.AddDevTunnel("public-api")
       .WithReference(web)
       .WithAnonymousAccess();

// After adding all resources, run the app...

The preceding code:

• Creates a new IDistributedApplicationBuilder instance.
• Adds a project reference to the web project.
• Adds a dev tunnel named public-api that exposes the web project.
• Configures the tunnel to allow anonymous access.

Configure dev tunnel options

To configure other options for the dev tunnel, provide the DevTunnelOptions to the AddDevTunnel method:

var builder = DistributedApplication.CreateBuilder(args);

var web = builder.AddProject<Projects.Web>("web");

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

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

// After adding all resources, run the app...

The preceding code:

• Creates a new IDistributedApplicationBuilder instance.
• Adds a project reference to the web project.
• Creates a DevTunnelOptions instance to configure the tunnel.
• Adds a dev tunnel named qa with a specific tunnelId that exposes the web project.
• Configures the tunnel with a description, labels, and disables anonymous access.

Configure for mixed access

To allow anonymous access to specific endpoints, use the appropriate WithReference overload as shown in the following code:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.ApiService>("api");

builder.AddDevTunnel("mixed-access")
       .WithReference(api.GetEndpoint("public"), allowAnonymous: true)
       .WithReference(api.GetEndpoint("admin")); // Requires authentication

// After adding all resources, run the app...

The preceding code:

• Creates a new IDistributedApplicationBuilder instance.
• Adds a project reference to the api project.
• Adds a dev tunnel named mixed-access that exposes:
  • The public endpoint of the api project with anonymous access.
  • The admin endpoint of the api project that requires authentication.

Service discovery integration

When another resource references a dev tunnel, environment variables are injected using the Aspire service discovery configuration format. Use the WithReference overloads that accept the IResourceBuilder<DevTunnelResource> parameter to reference a dev tunnel. This injects environment variables like:

WEB_HTTPS=https://myweb-1234.westeurope.devtunnels.ms/
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.

Configuration

Dev tunnel options

The DevTunnelOptions class provides several configuration options:

Dev tunnel port options

The DevTunnelPortOptions class provides configuration for individual tunnel ports:

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

Tunnel lifecycle

Dev tunnels automatically:

• Install the devtunnel CLI if not already available.
• Ensure the user is logged in to the dev tunnels service.
• Create and manage tunnel lifecycle.
• Clean up unmodeled ports from previous runs.
• Provide detailed logging and diagnostics.

Tunnels will expire after not being hosted for 30 days by default, so they won't be forcibly deleted when the resource or AppHost is stopped.

Troubleshooting

Authentication required

If you see authentication errors, ensure you're logged in to the dev tunnels service:

devtunnel user login

Port conflicts

If you encounter port binding issues, check that no other processes are using the same ports, or configure different ports for your endpoints.

Tunnel not accessible

Verify that:

• The tunnel is running and healthy in the Aspire dashboard.
• You're using the correct tunnel URL.
• Anonymous access is configured correctly if accessing without authentication.

See also

• Dev tunnels service documentation
• Dev tunnels FAQ
• Aspire service discovery
• Aspire networking overview