Test TUI and shell apps using WithTerminal

If you have a terminal user interface (TUI) application or a shell-based experience that you want to exercise while it runs under Aspire, add WithTerminalwithTerminal to the resource. Aspire then exposes an interactive terminal session that you can attach to from the Aspire dashboard or from the aspire terminal CLI command.

For an introduction to the resource Terminal view, terminal dock, and detached windows, start with Dashboard terminals.

Aspire 13.6 preview

This page describes resource-terminal behavior and defaults for Aspire 13.6 preview. Use matching AppHost, dashboard, and CLI builds.

Prerequisites

Start with a TypeScript or C# AppHost and an installed interactive program. Resource terminals support executable and project processes on Windows, macOS, and Linux, as well as container processes through the container runtime. Containers require a supported container runtime.

The following example runs Python’s interactive REPL. Install Python and ensure python3 is on the AppHost machine’s PATH; use python instead if that is your installation’s command, for example on Windows. It doesn’t require a Python source file.

Add an interactive resource

TypeScript

apphost.mts

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

const builder = await createBuilder();

await builder
  .addExecutable('repl', 'python3', '.', ['-i', '-q'])
  .withTerminal();

await builder.build().run();

C#

AppHost.cs

#pragma warning disable ASPIRETERMINAL001
var builder = DistributedApplication.CreateBuilder(args);

builder.AddExecutable("repl", "python3", ".", "-i", "-q")
    .WithTerminal();

builder.Build().Run();

Start the app with aspire run, select repl on the dashboard’s Console logs page, and switch to Terminal if needed. At the Python prompt, enter print("Hello from Aspire"). You can also run aspire terminal attach repl after enabling the CLI commands.

Experimental

WithTerminal is an experimental API. Calling it in C# produces the ASPIRETERMINAL001 diagnostic, which you must acknowledge for your AppHost to build. Suppress it inline with #pragma warning disable ASPIRETERMINAL001 (as shown in the C# example above), or add ASPIRETERMINAL001 to <NoWarn> in your project file. The shape of the API and its options may change in a future release.

When to use WithTerminal

Reach for WithTerminal when a resource is interactive rather than a plain background service:

• A TUI application—for example, an agent, a diagnostics console, or a curses-style tool—that draws a full-screen interface you want to see and drive.
• A shell-based experience where you want an interactive prompt inside a container or executable while it runs as part of your app model.
• An interactive development tool that you want to use without leaving the Aspire dashboard or CLI.

WithTerminal attaches to the resource’s configured process; it doesn’t open an additional shell inside an existing service. For that scenario, use an AppHost-owned container exec terminal.

Explore a complete application

The TypeScript terminal basics sample and C# terminal basics sample demonstrate this with a containerized REST client, an API, and Redis.

The TypeScript AppHost and C# AppHost build the client’s image with AddDockerfileaddDockerfile, pass the API endpoint through BASE_URL, wait for the API, and enable the terminal with WithTerminal(). The client runs as the resource’s main process; there is no separate client session to create.

Follow either sample’s README to send a request from the resource terminal, change the stored data through Redis’s separate REPL command, and read it back through the API. This illustrates the distinction between an interactive resource and an ephemeral terminal without requiring host installations of the client tools.

The debugger is not attached automatically

When you apply WithTerminal, Aspire runs the resource as a plain process and does not automatically attach the debugger. If you need to debug the resource, attach the debugger manually to the running process from your IDE.

टिप्पणी

The orchestrator (DCP) cannot currently run a process under the debugger and a pseudo-terminal (PTY) at the same time, so Aspire favors interactive terminal execution over automatic IDE execution.

Attach from multiple places at once

Terminal sessions support multiple simultaneous viewers. You can open two browser tabs pointing at the same terminal, or a browser tab and the CLI together. They share the same process and screen, not separate shells. Coordinate input when another person or automation is attached.

One peer holds the primary role and drives the terminal’s dimensions, while the others attach as secondary viewers. From the CLI you can attach without taking sizing control with aspire terminal attach <resource> --viewer, and take control later with the Ctrl+B T hotkey. A secondary viewer isn’t an exclusive-input or read-only boundary.

Configure the terminal

To query a running database or cache, use the integration’s WithRepl() command instead. It opens an additional client in the terminal dock without changing the server’s main process. WithTerminal() is for a resource whose main process needs an interactive terminal.

The terminal session is described by a set of options with sensible defaults:

Option	Default	Description
Columns	120	The initial number of columns for the terminal grid.
Rows	30	The initial number of rows for the terminal grid.
ShowTerminalHost	false	Whether the hidden per-replica terminal host resources appear in the dashboard and CLI resource lists and export their diagnostic logs, metrics, and traces. Set to true to diagnose terminal-host startup or connectivity issues.

संकेत

Columns and Rows must each be 1 or greater. Configuring either with zero or a negative value in the WithTerminal(...) callback throws an ArgumentOutOfRangeException immediately instead of failing later during terminal-host startup.

Terminal host telemetry is opt-in

By default, the hidden terminal host helper resources don’t export logs, metrics, or traces, even when an OTLP endpoint is configured for the app—so they never show up in the dashboard’s telemetry resource list (including the Traces filter). Setting ShowTerminalHost = true both reveals the helper resources and turns on their diagnostic telemetry when an OTLP endpoint is available. This is independent of the parent resource’s own telemetry, which is never affected by WithTerminal.

टिप्पणी

The resource being run is always the terminal program: for executables that’s the process itself, and for containers it’s the container’s own process. Configure the executable or container command to select the program; TerminalOptions doesn’t have a shell-selection option. Initial dimensions can later change when a viewer takes sizing control.

TypeScript

TypeScript’s withTerminal() currently applies the default options. Configuring initial dimensions through a TypeScript options overload isn’t supported.

apphost.mts

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

const builder = await createBuilder();

await builder
  .addExecutable('repl', 'python3', '.', ['-i', '-q'])
  .withTerminal();

await builder.build().run();

C#

In C#, pass a callback to override any of these options:

AppHost.cs

#pragma warning disable ASPIRETERMINAL001
var builder = DistributedApplication.CreateBuilder(args);

builder.AddExecutable("repl", "python3", ".", "-i", "-q")
    .WithTerminal(options =>
    {
        options.Columns = 200;
        options.Rows = 50;
    });

builder.Build().Run();

Terminals and replicas

Each replica of a resource gets its own independent terminal session. Aspire creates one terminal host per parent replica, so requesting three replicas yields three separate terminals. The order of WithReplicaswithReplicas and WithTerminal does not matter. For a project-based interactive app in ../Agent/Agent.csproj:

TypeScript

apphost.mts

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

const builder = await createBuilder();

await builder
  .addProject('agent', '../Agent/Agent.csproj')
  .withReplicas(3)
  .withTerminal();

await builder.build().run();

C#

Add a project reference to Agent.csproj in your AppHost before using its generated Projects.Agent type.

AppHost.cs

#pragma warning disable ASPIRETERMINAL001
var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.Agent>("agent")
    .WithReplicas(3)
    .WithTerminal();

builder.Build().Run();

When a resource has more than one replica, choose which one to attach to with aspire terminal attach <resource> --replica <index> (indices are 0-based), or pick interactively when prompted.

टिप्पणी

Add a terminal to a resource only once. Calling WithTerminal() more than once on the same resource throws an exception.

View terminals in the dashboard

When a resource has WithTerminal applied, its Console logs page gains a live terminal session alongside the usual console log stream. Select a replica to interact with its independent session.

The page picks a default view based on the resource’s state at the moment you navigate to it:

• Running (the PTY is live) → the page defaults to the Terminal view, so the interactive session is the first thing you see.
• Waiting/Starting or already Exited/Finished/FailedToStart → the page defaults to the Console logs view, so hosting messages—such as “Waiting for resource X to become healthy…” or a startup failure—and post-exit output remain visible immediately.

Select Settings in the page toolbar and choose Terminal or Console logs to switch views manually at any time. Both views stay live while you’re on the page: switching between them never tears down the terminal session or loses console log scrollback, and a later state transition (for example, Waiting → Running) doesn’t auto-switch the view once you’ve navigated to the page. Selecting a different resource re-evaluates the default for that resource.

टिप्पणी

The view you pick only affects what’s currently displayed—it doesn’t change what’s captured. Console logs keep streaming, and the terminal session keeps running, regardless of which view is active.

For detached windows, font and sizing controls, keyboard focus navigation, and lifecycle differences, see Dashboard terminals.

Container startup output

The container runtime can start a container before attaching its terminal. One-time startup output and terminal capability queries can be missed. For tools that depend on those queries, start an interactive shell as the container process and launch the tool after attaching.

Firefox renderer

Desktop and Android Firefox always render dashboard terminals using WebGL2, even when WebGPU is available, to avoid a known Firefox WebGPU performance issue. This applies to every terminal mount—including automatic retries and explicit reconnects—and requires no configuration. Firefox on iOS (FxiOS/) uses WebKit rather than Gecko, so it isn’t affected and keeps automatic renderer selection like other browsers.

Because a terminal-backed executable bridges its standard output and error through the pseudo-terminal (PTY) instead of separate log streams, the Console logs view and aspire logs only show that resource’s startup and system logs. For example the view shows lifecycle and DCP diagnostics but not the interleaved stdout and stderr text you see in the Terminal view. Use the Terminal view or aspire terminal attach <resource> to see the process’s own output.

Open a terminal in a separate window

Use Open in new window to keep a terminal visible while you inspect other dashboard pages. AppHost-owned terminal dock tabs can also open in a separate window, as shown below. Their detached view contains the terminal and its controls rather than the dashboard navigation.

Resource terminals and AppHost-owned dock terminals have different ownership and lifetimes. Closing a viewer doesn’t replace disposing an AppHost-owned terminal. For more about docked terminals, see Explore the Aspire dashboard.

Access terminals from VS Code

In the Aspire VS Code extension, any resource configured with WithTerminal() gains an Open terminal entry in its right-click context menu. Selecting Open terminal runs aspire terminal attach <resource> and opens the session as an editor-style terminal tab directly in VS Code—no separate shell window needed.

For multi-replica resources, the extension automatically passes --replica <index> so the correct instance is attached. The --apphost flag is included when the current AppHost connection information is available, so the command connects without requiring you to specify the AppHost separately.

टिप्पणी

The Open terminal context-menu item is only visible for resources that have terminal.enabled set, which is the case for any resource where WithTerminal() was called in the AppHost. Resources without WithTerminal() do not show this menu entry.

Work with terminals from the CLI

The aspire terminal command group lets you list and attach to terminal sessions from your shell without any configuration step:

• aspire terminal ps lists every terminal-enabled resource in the running AppHost, with grid size, attached-peer count, and per-replica health.
• aspire terminal attach attaches your local terminal to a resource’s interactive PTY session.
• aspire terminal tape play drives an existing resource terminal with scripted input and output waits. See terminal automation for complete examples and tape file syntax.

See also

• aspire terminal command
• Executable resources
• Dashboard terminal experiences
• Create AppHost-owned terminals