Dev Tunnels integration

Dev tunnels allow developers to securely share local web services across the internet. Enabling you to connect your local development environment with cloud services, share work in progress with colleagues or aid in building webhooks. Dev tunnels is for adhoc testing and development, not for production workloads.

위험

Dev tunnels are for ad-hoc testing and development, not for production workloads.

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

참고

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.

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 Dev Tunnels integration, install the 📦 Aspire.Hosting.DevTunnels NuGet package in the AppHost project:

TypeScript

Terminal

aspire add devtunnels

This updates your aspire.config.json with the Dev Tunnels hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.DevTunnels": "13.6.0"
  }
}

C#

Aspire CLI

Aspire CLI — Aspire.Hosting.DevTunnels 패키지 추가

aspire add devtunnels

Aspire CLI는 대화형입니다. 프롬프트 시 알맞은 검색 결과 선택:

Aspire CLI — 출력 예시

Select an integration to add:

> devtunnels (Aspire.Hosting.DevTunnels)
> Other results listed as selectable options...

참고

결과가 하나라면 자동 선택됩니다. 버전은 직접 확인해야 합니다.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.DevTunnels@*

PackageReference (*.csproj)

XML — Aspire.Hosting.DevTunnels 패키지 참조 추가

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

Add a dev tunnel resource

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

TypeScript

apphost.mts

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

const builder = await createBuilder();

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

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

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

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:

TypeScript

apphost.mts

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

const builder = await createBuilder();

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

const tunnel = await builder.addDevTunnel("public-api")
    .withReference(web)
    .withAnonymousAccess();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

Configure dev tunnel options

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

TypeScript

apphost.mts

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

const builder = await createBuilder();

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

const tunnel = await builder.addDevTunnel("qa", "my-tunnel-id", false, "QA environment tunnel", ["qa", "testing"])
    .withReference(web);

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

var tunnel = builder.AddDevTunnel("qa", tunnelId: "my-tunnel-id", options: options)
                    .WithReference(web);

Configure for mixed access

To allow anonymous access to specific endpoints, use the appropriate WithReference overload:

TypeScript

apphost.mts

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

const builder = await createBuilder();

const api = await builder.addNodeApp("api", "../api", "index.js");

const tunnel = await builder.addDevTunnel("mixed-access")
    .withReference(api, "public", { allowAnonymous: true })
    .withReference(api, "admin", { allowAnonymous: false });

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var tunnel = builder.AddDevTunnel("mixed-access")
                    .WithReference(api, "public", allowAnonymous: true)
                    .WithReference(api, "admin", allowAnonymous: false);

The preceding code exposes:

• The public endpoint of the api project with anonymous access
• The public endpoint of the api project with anonymous access.
• The admin endpoint of the api project that requires authentication.

Show tunnel URLs

While the dev tunnel is running, the Aspire dashboard publishes the public tunnel URL, the inspect URL, and the local endpoint URL as highlighted properties on the tunnel port resource’s property pane so they’re discoverable at a glance.

You can also select the highlighted Show tunnel URLs command from the tunnel port resource’s command menu in the dashboard. This opens a message box listing:

• Tunnel URL — the public dev tunnel URL for the port
• Inspect URL — the Dev Tunnels inspection URL for viewing tunneled HTTP traffic
• Local endpoint URL — the local address the tunnel forwards to, once allocated

참고

The Show tunnel URLs command is only enabled once the tunnel port is running and its public URL has been allocated.

Service discovery integration

When another resource references a dev tunnel, environment variables are injected using the Aspire service discovery configuration format:

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.

참고

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

위험

Dev tunnels are a development time concern only and aren’t included when publishing or deploying an AppHost, including any service discovery information.

Configuration

Use the following properties to configure you dev tunnels:

Dev tunnel options

The DevTunnelOptions class provides several configuration options:

Property	Description
Description	A description for the tunnel that appears in the dev tunnels service
Labels	A list of labels to apply to the tunnel for organization and filtering
AllowAnonymous	Whether to allow anonymous access to the entire tunnel
Region	The DevTunnelRegion to create the tunnel in; automatic when unset

참고

Region is only configurable in C# via DevTunnelOptions. The non-C# TypeScript addDevTunnel export doesn’t surface a region parameter.

Dev tunnel port options

The DevTunnelPortOptions class provides configuration for individual tunnel ports:

Property	Description
Protocol	The protocol to use (http, https, or auto). If not specified, uses the endpoint’s scheme
Description	A description for this specific port
Labels	Labels to apply to this port
AllowAnonymous	Whether to allow anonymous access to this specific port

Security recommendations

• 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
• 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

Dashboard doesn’t show a tunnel URL

Dev tunnel endpoints stay unallocated until the integration publishes the real tunnel endpoint. The dashboard and MCP resource snapshots then show the public tunnel URL.

If you’re using Aspire 13.5 and the resource reaches the Running and Healthy states without showing a URL, update to Aspire 13.6 or later to resolve a known endpoint-publication regression.

See also

• Dev tunnels overview
• Dev tunnels CLI installation
• Aspire integrations overview
• AppHost overview
• Aspire GitHub repo