Mitch Denny (mitchdenny) · Jun 10, 2026 · Apr 20, 2026 · Apr 20, 2026 · Apr 20, 2026 · Apr 20, 2026
diff --git a/Aspire.slnx b/Aspire.slnx
@@ -81,6 +81,7 @@
     <Project Path="src/Aspire.Hosting.Blazor/Aspire.Hosting.Blazor.csproj" />
     <Project Path="src/Aspire.Hosting.Yarp/Aspire.Hosting.Yarp.csproj" />
     <Project Path="src/Aspire.Hosting/Aspire.Hosting.csproj" />
+    <Project Path="src/Aspire.TerminalHost/Aspire.TerminalHost.csproj" />
     <Project Path="src/Aspire.TypeSystem/Aspire.TypeSystem.csproj" />
     <Project Path="src/Aspire.ProjectTemplates/Aspire.ProjectTemplates.csproj" />
   </Folder>
@@ -383,6 +384,10 @@
     <Project Path="playground/Stress/Stress.Empty/Stress.Empty.csproj" />
     <Project Path="playground/Stress/Stress.TelemetryService/Stress.TelemetryService.csproj" />
   </Folder>
+  <Folder Name="/playground/Terminals/">
+    <Project Path="playground/Terminals/Terminals.AppHost/Terminals.AppHost.csproj" />
+    <Project Path="playground/Terminals/Terminals.Repl/Terminals.Repl.csproj" />
+  </Folder>
   <Folder Name="/playground/Testing/">
     <Project Path="playground/Testing/Testing.Tests/Testing.Tests.csproj" />
   </Folder>
@@ -536,6 +541,7 @@
     <Project Path="tests/Aspire.Hosting.SqlServer.Tests/Aspire.Hosting.SqlServer.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Testing.Tests/Aspire.Hosting.Testing.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj" />
+    <Project Path="tests/Aspire.TerminalHost.Tests/Aspire.TerminalHost.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Valkey.Tests/Aspire.Hosting.Valkey.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Blazor.Tests/Aspire.Hosting.Blazor.Tests.csproj" />
     <Project Path="tests/Aspire.Hosting.Yarp.Tests/Aspire.Hosting.Yarp.Tests.csproj" />

diff --git a/Directory.Build.props b/Directory.Build.props
@@ -32,6 +32,7 @@
     <SkipAspireWorkloadManifest>true</SkipAspireWorkloadManifest>
 
     <DashboardPublishedArtifactsOutputDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'DashboardArtifacts', '$(Configuration)'))</DashboardPublishedArtifactsOutputDir>
+    <TerminalHostPublishedArtifactsOutputDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'TerminalHostArtifacts', '$(Configuration)'))</TerminalHostPublishedArtifactsOutputDir>
     <WorkloadsPackageSource>$(ArtifactsShippingPackagesDir)</WorkloadsPackageSource>
 
     <!-- Issue: https://github.com/microsoft/aspire/issues/8488 -->
@@ -55,6 +56,7 @@
     <!-- TODO: Need to figure out we can automatically detect target framework here. This property
                is specified to support dashboard path metadata generation on the inner loop. -->
     <AspireDashboardDir>$(MSBuildThisFileDirectory)/artifacts/bin/Aspire.Dashboard/$(Configuration)/net8.0/</AspireDashboardDir>
+    <AspireTerminalHostDir>$(MSBuildThisFileDirectory)/artifacts/bin/Aspire.TerminalHost/$(Configuration)/net8.0/</AspireTerminalHostDir>
   </PropertyGroup>
 
 </Project>
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -101,9 +101,9 @@
     <PackageVersion Include="Grpc.AspNetCore" Version="2.80.0" />
     <PackageVersion Include="Grpc.Net.ClientFactory" Version="2.80.0" />
     <PackageVersion Include="Grpc.Tools" Version="2.80.0" />
-    <PackageVersion Include="Hex1b" Version="0.154.0" />
-    <PackageVersion Include="Hex1b.McpServer" Version="0.154.0" />
-    <PackageVersion Include="Hex1b.Tool" Version="0.154.0" />
+    <PackageVersion Include="Hex1b" Version="0.163.0" />
+    <PackageVersion Include="Hex1b.McpServer" Version="0.163.0" />
+    <PackageVersion Include="Hex1b.Tool" Version="0.163.0" />
     <PackageVersion Include="Humanizer.Core" Version="3.0.10" />
     <PackageVersion Include="KubernetesClient" Version="19.0.2" />
     <PackageVersion Include="JsonPatch.Net" Version="5.0.2" />

diff --git a/docs/specs/with-terminal.md b/docs/specs/with-terminal.md
@@ -0,0 +1,166 @@
+# `WithTerminal()` — Aspire interactive terminal architecture
+
+**Status:** Implemented for Aspire 13.4 (Windows executables).
+**Issue:** [microsoft/aspire#16317](https://github.com/microsoft/aspire/issues/16317)
+**DCP integration:** [microsoft/dcp#133](https://github.com/microsoft/dcp/pull/133)
+
+## Goal
+
+Let an Aspire AppHost author opt any executable or container resource into
+interactive terminal access:
+
+```csharp
+builder.AddProject<Projects.MyAgent>("agent")
+    .WithReplicas(2)
+    .WithTerminal();
+```
+
+The dashboard then renders an xterm.js terminal per replica, and the CLI
+exposes the same session as `aspire terminal agent --replica 0`.
+
+## Process topology
+
+```text
+                                ┌────────────────────────────┐
+                                │  AppHost (dotnet run)      │
+                                │  - Aspire.Hosting          │
+                                │  - DCP control plane       │
+                                │  - per-replica:            │
+                                │    Aspire.TerminalHost     │  (1 process per replica)
+                                └─────────────┬──────────────┘
+                                              │ spawn
+                                              ▼
+┌──────────────────────┐                ┌───────────────────────┐                ┌────────────────────────┐
+│  DCP-launched        │   PTY          │  TerminalHost         │   HMP v1 UDS   │  Consumers             │
+│  replica process     │ ─────────────▶ │  (Hex1b HMP v1 broker) │ ─────────────▶ │  - Dashboard          │
+│  (executable, repl…) │ ◀───── stdin ─ │                       │ ◀───── input ─ │    /api/terminal proxy │
+└──────────────────────┘                └───────────────────────┘                │  - aspire CLI          │
+                                                                                  └────────────────────────┘
+```
+
+Three actors and three socket roles:
+
+| Actor          | Socket              | Direction                        | Lifetime |
+|----------------|---------------------|----------------------------------|----------|
+| **DCP**        | `producerUdsPath`   | DCP → host (PTY bytes + control) | Per replica |
+| **TerminalHost** | `consumerUdsPath` | host → consumers (broadcast)     | Per replica |
+| **TerminalHost** | `controlUdsPath`  | AppHost → host (lifecycle, stats)| Per replica |
+
+The producer/consumer split lets multiple consumers (dashboard + multiple CLI
+sessions) attach simultaneously without coupling DCP to consumer counts.
+
+## Wire protocol
+
+We do **not** define a custom protocol. The terminal traffic uses
+[Hex1b](https://github.com/dotnet/hex1b)'s `HMP v1` (Hex Multiplex Protocol,
+version 1), which already handles:
+
+- VT byte streaming with backpressure
+- Resize requests in both directions
+- Hello/StateSync replay so a late-attaching consumer sees the current
+  scrollback
+- Connection lifecycle (close, disconnect, reconnect)
+- Authenticated stream factory hooks (we only use Unix-socket transport
+  today)
+
+The `Hmp1WorkloadAdapter` is what the AppHost-side terminal host uses to
+multiplex DCP's PTY traffic to the consumer-facing listener; the
+`Hmp1PresentationAdapter` is what consumers (Dashboard WebSocket proxy and
+the CLI) use to attach.
+
+## Property contract (gRPC `ResourceService` snapshots)
+
+When `WithTerminal()` is applied to a resource, every replica snapshot
+emitted by the dashboard service carries four properties:
+
+| Key                       | Sensitivity     | Meaning                                      |
+|---------------------------|-----------------|----------------------------------------------|
+| `terminal.enabled`        | non-sensitive   | Marker. `"true"` when the replica has a PTY. |
+| `terminal.replicaIndex`   | non-sensitive   | 0-based stable index from `DcpInstancesAnnotation`. |
+| `terminal.replicaCount`   | non-sensitive   | Total replicas for the parent resource.      |
+| `terminal.consumerUdsPath`| **sensitive**   | The local UDS that consumers connect to.     |
+
+The consumer UDS path is marked `IsSensitive=true` so the dashboard UI masks
+the value in the property list. The path still rides the gRPC stream because
+the dashboard's WebSocket proxy needs it server-side to resolve
+`?resource=&replica=` query parameters into a real socket; the path is never
+echoed back to the browser.
+
+## Dashboard `/api/terminal` WebSocket endpoint
+
+Authenticated (`RequireAuthorization(FrontendAuthorizationDefaults.PolicyName)`)
+endpoint at `/api/terminal?resource=<displayName>&replica=<index>`.
+
+`TerminalWebSocketProxy` resolves the connection entirely server-side:
+
+1. `ITerminalConnectionResolver.ConnectAsync(resourceName, replicaIndex, ct)`
+   walks `IDashboardClient.GetResources()`, matches by `DisplayName` +
+   `TryGetTerminalReplicaInfo`, and connects via
+   `Hmp1Transports.ConnectUnixSocket(consumerUdsPath, ct)`.
+2. The proxy wraps the resulting stream in `Hmp1WorkloadAdapter` and runs
+   two pumps:
+   - **Inbound (browser → producer):** binary frames are forwarded as HMP v1
+     `Input` (keystrokes); text frames are parsed as JSON resize control
+     messages (`{"type":"resize","cols":N,"rows":N}`).
+   - **Outbound (producer → browser):** VT bytes from the producer become
+     binary WebSocket frames; resize hints from the producer become JSON
+     text frames.
+3. Frame type — not content — distinguishes keystroke from control. This
+   keeps the proxy's parser cheap and avoids ambiguity around binary input
+   that happens to look like JSON.
+4. Multi-fragment WS reads are reassembled in `ReassembledFrame` using
+   `ArrayPool<byte>`.
+
+The browser never sees `consumerUdsPath` and cannot induce the dashboard
+to connect to an arbitrary local socket — it can only ask for
+`(resource, replica)` pairs that are present in the resource snapshot
+stream.
+
+## CLI
+
+`aspire terminal <resource> [--replica N]` (`Aspire.Cli/Commands/TerminalCommand.cs`)
+opens its own `Hmp1PresentationAdapter` against the consumer UDS path
+returned by `IBackchannel.GetTerminalInfoAsync(resource, replica)` and
+renders frames into the host terminal via Hex1b's `Hex1bTerminal`. When the
+resource has more than one replica and the CLI is interactive, it prompts
+for a selection; in non-interactive mode the `--replica` flag is required.
+
+## DCP integration
+
+For each replica of a `WithTerminal()` resource, DCP allocates a pseudo-terminal
+when the executable (or container) spec carries a populated `terminal` block:
+
+```json
+{
+  "terminal": {
+    "udsPath":    "/run/user/1000/aspire/trmnl/<run-id>/<resource>-<idx>/producer.sock",
+    "socketMode": "connect",
+    "cols":       120,
+    "rows":       30
+  }
+}
+```
+
+`socketMode: "connect"` tells DCP to dial the named UDS (the TerminalHost
+process owns the listener). The dimensions are the initial PTY size; both
+sides exchange resize frames over HMP afterwards.
+
+Desktop PTY support is implemented across all three platforms (Unix98 `/dev/ptmx` on Linux and macOS; ConPTY on Windows). Container PTYs are tracked
+as a Phase 3 follow-up on the parent issue.
+
+## Files of interest
+
+| Concern                              | File                                                                |
+|--------------------------------------|---------------------------------------------------------------------|
+| Public API entry point               | `src/Aspire.Hosting/TerminalResourceBuilderExtensions.cs`           |
+| Per-resource hidden host resource    | `src/Aspire.Hosting/ApplicationModel/TerminalHostResource.cs`       |
+| DCP wire-up                          | `src/Aspire.Hosting/Dcp/ExecutableCreator.cs`                       |
+| Backchannel `GetTerminalInfoAsync`   | `src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs`   |
+| Snapshot stamping                    | `src/Aspire.Hosting/Dashboard/DashboardServiceData.cs`              |
+| TerminalHost process                 | `src/Aspire.TerminalHost/`                                          |
+| CLI command                          | `src/Aspire.Cli/Commands/TerminalCommand.cs`                        |
+| Dashboard WebSocket proxy            | `src/Aspire.Dashboard/Terminal/TerminalWebSocketProxy.cs`           |
+| Dashboard resolver                   | `src/Aspire.Dashboard/Terminal/DefaultTerminalConnectionResolver.cs`|
+| `TerminalView` (xterm.js host)       | `src/Aspire.Dashboard/Components/Controls/TerminalView.razor.*`     |
+| Property keys                        | `src/Shared/Model/KnownProperties.cs` (`Terminal.*`)                |
+| Playground sample                    | `playground/Terminals/Terminals.AppHost/AppHost.cs`                 |
diff --git a/eng/Build.props b/eng/Build.props
@@ -7,8 +7,8 @@
       BuildTestsOnly         - if 'true', builds only test projects, defaults to 'false'
       SkipTestProjects       - if 'true', skips building test projects, defaults to 'false'
       SkipPlaygroundProjects - if 'true', skips building playground projects, defaults to 'false'
-      SkipBundleDeps         - if 'true', skips building eng/dcppack, eng/dashboardpack, Aspire.Dashboard, and Aspire.Cli projects during the main managed build, defaults to 'false'
-      BuildBundleDepsOnly    - if 'true', builds only the RID-specific eng/dcppack and eng/dashboardpack projects for $(TargetRids), plus Aspire.Dashboard for restore, defaults to 'false'
+      SkipBundleDeps         - if 'true', skips building eng/dcppack, eng/dashboardpack, Aspire.Dashboard, Aspire.TerminalHost, and Aspire.Cli projects during the main managed build, defaults to 'false'
+      BuildBundleDepsOnly    - if 'true', builds only the RID-specific eng/dcppack and eng/dashboardpack projects for $(TargetRids), plus Aspire.Dashboard and Aspire.TerminalHost for restore, defaults to 'false'
       TargetRids             - colon separated list of RIDs to build native projects for
   -->
 
@@ -34,6 +34,10 @@
     <!-- Dashboard is invoked by dashboardpack via MSBuild task (not ProjectReference),
          so it must be explicitly included to ensure restore generates its assets file. -->
     <ProjectToBuild Include="$(RepoRoot)src\Aspire.Dashboard\Aspire.Dashboard.csproj" />
+    <!-- TerminalHost is shipped only via the CLI managed bundle (no per-RID packaging
+         project), but it still needs to be restored so the bundle build can copy its
+         publish output. -->
+    <ProjectToBuild Include="$(RepoRoot)src\Aspire.TerminalHost\Aspire.TerminalHost.csproj" />
   </ItemGroup>
 
   <!-- `$(BuildTestsOnly)` allows building only test projects, skipping the following directories:
@@ -48,6 +52,7 @@
     <ProjectToBuild Remove="$(RepoRoot)src\Aspire.Cli\Aspire.Cli.Tool.csproj" />
     <ProjectToBuild Remove="$(RepoRoot)src\Aspire.Cli\Aspire.Cli.csproj" Condition="'$(SkipBundleDeps)' == 'true'" />
     <ProjectToBuild Remove="$(RepoRoot)src\Aspire.Dashboard\Aspire.Dashboard.csproj" Condition="'$(SkipBundleDeps)' == 'true'" />
+    <ProjectToBuild Remove="$(RepoRoot)src\Aspire.TerminalHost\Aspire.TerminalHost.csproj" Condition="'$(SkipBundleDeps)' == 'true'" />
     <ProjectToBuild Include="$(RepoRoot)eng\dcppack\**\*.csproj" Condition="'$(SkipBundleDeps)' != 'true'" />
     <ProjectToBuild Include="$(RepoRoot)eng\dashboardpack\**\*.csproj" Condition="'$(SkipBundleDeps)' != 'true'" />
 

diff --git a/playground/Stress/Stress.AppHost/CommandResources.cs b/playground/Stress/Stress.AppHost/CommandResources.cs
@@ -877,7 +877,7 @@ private static void AddTelemetryCommands(IDistributedApplicationBuilder builder,
                 displayName: "Stop all resources",
                 executeCommand: async (c) =>
                 {
-                    await ExecuteCommandForAllResourcesAsync(c.ServiceProvider, KnownResourceCommands.StopCommand, c.CancellationToken);
+                    await ExecuteCommandForAllResourcesAsync(c.Services, KnownResourceCommands.StopCommand, c.CancellationToken);
                     return CommandResults.Success();
                 },
                 commandOptions: new() { IconName = "Stop", IconVariant = IconVariant.Filled })
@@ -886,7 +886,7 @@ private static void AddTelemetryCommands(IDistributedApplicationBuilder builder,
                 displayName: "Start all resources",
                 executeCommand: async (c) =>
                 {
-                    await ExecuteCommandForAllResourcesAsync(c.ServiceProvider, KnownResourceCommands.StartCommand, c.CancellationToken);
+                    await ExecuteCommandForAllResourcesAsync(c.Services, KnownResourceCommands.StartCommand, c.CancellationToken);
                     return CommandResults.Success();
                 },
                 commandOptions: new() { IconName = "Play", IconVariant = IconVariant.Filled });