Skip to content

Add opt-in AppHost Server v2 to the CLI bundle - #20897

Merged
David Fowler (davidfowl) merged 68 commits into
mainfrom
davidfowl/lean-native-runtime-feasibility
Oct 21, 2026
Merged

David Fowler (davidfowl) merged 68 commits into
mainfrom
davidfowl/lean-native-runtime-feasibility

Conversation

@davidfowl

@davidfowl David Fowler (davidfowl) commented Oct 10, 2026 •

Copy link
Copy Markdown
Collaborator

Description

The Aspire CLI is the single entry point: aspire run / aspire start / aspire deploy. Each command uses the same application model; what changes is how that model is executed.

This PR introduces AppHost Server v2, separating application authoring from execution. AppHost code describes the application through generated ATS contracts. A separate, long-lived server owns the graph, pipeline scheduling, and workload lifetimes.

Architecture

Today, C# authoring runs inside the managed AppHost while guests connect over ATS. The v2 direction unifies all authoring languages over ATS to a NativeAOT AppHost, with a minimal-dependency kernel and integration hosts in any language. All CLI operations remain server-orchestrated.

The server's minimal-dependency kernel owns declarations, references, revisions, and execution authority. Integration-specific libraries stay outside it: portable modules compose the model in the guest, while integration hosts provide runtime services in separate processes. NativeAOT and build-time ATS generation keep runtime scanning and code generation off the execution path.

Authoring and execution have independent lifetimes. A guest can disconnect or submit a new revision without inherently restarting compatible workloads. The server validates and schedules pipeline steps; their integration-specific callbacks execute in the guest. Local execution uses DCP and the existing Dashboard. Deployment integrations, such as Compose, consume the same model without becoming part of the kernel.

Scope

Opt in per project in aspire.config.json:

{
  "features": {
    "appHostServerV2": true
  }
}

Existing AppHosts continue using managed Hosting by default, with no change to its behavior.

The first CLI slice supports TypeScript/Node.js on Windows and Unix. The PR also includes standalone C# prototypes and side-by-side TypeScript/C# Compose integrations. Compose publishing and deployment are bounded, nonshipping demonstrations, not managed Compose parity. Automatic CLI reload, broader integration support, and formal security review remain follow-up work.

Real CLI validation covers run, detached start, publish, and deploy, including shutdown and Redis persistence. Linux NativeAOT and Windows named-pipe validation passed.

Related to #20873. See the App Model v2 specification for details. This PR remains draft.

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

Add an isolated Native AOT resource core, unchanged managed Redis execution, a TypeScript Nuxt integration process, and a real workload/deployment-context harness. Record the ownership, orchestration, publishing, containment, and measurement limitations without changing production behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
Exercise managed facades, real C# reference and lifecycle helpers, cross-owner startup, endpoint rebinding, owner invalidation, manifest publishing, and native-only activation. Document the proven boundaries and implementation scope.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
Exercise native containers, database children, executable readiness, deferred values, restart persistence, and owner-scoped cleanup. Preserve a mixed path through the unchanged managed Redis integration and document the production gaps.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
Add run-only custom endpoints with owner/generation fencing, deferred URL consumers, command cancellation, DCP log observation, and owner invalidation. Exercise real DCP and HTTP forwarding with an explicit local CLI fixture; record live relay validation as blocked by expired authentication.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
Generate the real ATS guest SDK and static AOT dispatch from a minimal primitive contract. Replatform bounded Redis, PostgreSQL and Dev Tunnels integrations, exercise actual DCP workloads, and demonstrate guest graph replacement with persistent native server and integration host processes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
Integrate direct AOT-safe DCP bootstrap and execution-document cleanup, embed the offline ATS SDK, and reuse CLI process and session lifetimes through an explicit headless override. Add real CLI workload and failure scenarios, focused regression coverage, and runnable samples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 20897

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 20897"

@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot October 10, 2026 16:40
@github-actions github-actions Bot added the area-integrations Issues pertaining to Aspire Integrations packages label Oct 10, 2026
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The override leaks into unsupported CLI operations, alters managed shutdown behavior, retains a DCP startup race, and leaves the principal PoC outside CI coverage.

4 open findings
What changed in this PR

This draft PoC explores a NativeAOT AppHost server with ATS-owned resource state while integrations execute in external processes.

Changes:

  • Adds native ATS dispatch, resource modeling, DCP orchestration, and lifecycle management.
  • Ports Redis, PostgreSQL, Nuxt, and development-tunnel scenarios to projected ATS APIs.
  • Adds an opt-in CLI server override, tests, authoring documentation, and compatibility harnesses.
File Description
docs/​specs/​appmodelv2.md Documents the proposed ATS-native authoring model.
playground/​NativeHosting/​.gitignore Excludes generated PoC artifacts.
playground/​NativeHosting/​README.md Describes architecture, usage, and limitations.
playground/​NativeHosting/​RpcPeer.cs Implements integration-host RPC transport.
playground/​NativeHosting/​apphost.mts Provides the original compatibility sample.
playground/​NativeHosting/​ats-apphost.mts Composes the ATS-native sample application.
playground/​NativeHosting/​ats-e2e.mts Exercises the standalone ATS scenario.
playground/​NativeHosting/​ats-guest.mts Implements guest-side ATS interaction.
playground/​NativeHosting/​ats-integration-host.mts Hosts external TypeScript integrations.
playground/​NativeHosting/​ats-ports.mts Ports integration behavior to ATS primitives.
playground/​NativeHosting/​cli-e2e.mts Exercises the native server through the CLI.
playground/​NativeHosting/​devtunnel-fixture.mts Provides local tunnel forwarding.
playground/​NativeHosting/​devtunnel-integration.mts Implements the tunnel integration.
playground/​NativeHosting/​devtunnel-output.mts Parses tunnel process output.
playground/​NativeHosting/​integration-ports.mts Defines compatibility integration ports.
playground/​NativeHosting/​managed-consumer.mts Exercises managed-resource consumption.
playground/​NativeHosting/​native-ports.mts Defines native resource projections.
playground/​NativeHosting/​native-tunnels.mts Defines native tunnel behavior.
playground/​NativeHosting/​nuxt-integration.mts Implements the Nuxt integration port.
playground/​NativeHosting/​tunnel-consumer.mts Exercises tunnel consumption.
playground/​NativeHosting/​Ats/​IntegrationContracts.cs Defines integration RPC contracts.
playground/​NativeHosting/​Ats/​NativeApi.cs Defines projected native capabilities.
playground/​NativeHosting/​Ats/​NativeHosting.Ats.csproj Configures the ATS contract project.
playground/​NativeHosting/​AtsCodegen/​CompatibleCodegen.cs Generates the bounded compatibility SDK.
playground/​NativeHosting/​AtsCodegen/​NativeHosting.AtsCodegen.csproj Configures the code-generation helper.
playground/​NativeHosting/​AtsCodegen/​Program.cs Runs ATS scanning and generation.
playground/​NativeHosting/​AtsServer/​AtsSession.cs Manages authenticated ATS sessions and handles.
playground/​NativeHosting/​AtsServer/​CompatibleContract.json Describes the bounded compatibility contract.
playground/​NativeHosting/​AtsServer/​CompatibleDispatch.cs Dispatches compatibility capabilities.
playground/​NativeHosting/​AtsServer/​NativeCliBootstrap.cs Bootstraps CLI-native server interaction.
playground/​NativeHosting/​AtsServer/​NativeDispatch.g.cs Contains generated native dispatch code.
playground/​NativeHosting/​AtsServer/​NativeHosting.AtsServer.csproj Configures NativeAOT server publishing.
playground/​NativeHosting/​AtsServer/​Program.cs Starts the native ATS server.
playground/​NativeHosting/​Core/​NativeCustomResources.cs Implements controller-owned custom resources.
playground/​NativeHosting/​Core/​NativeDcp.cs Executes workloads through the DCP API.
playground/​NativeHosting/​Core/​NativeHosting.Core.csproj Configures the native core project.
playground/​NativeHosting/​Core/​NativeModel.cs Implements the native resource graph.
playground/​NativeHosting/​Core/​Program.cs Runs the standalone native core.
playground/​NativeHosting/​ManagedAdapter/​ManagedEdges.cs Bridges managed integration behavior.
playground/​NativeHosting/​ManagedAdapter/​NativeHosting.ManagedAdapter.csproj Configures the managed adapter.
playground/​NativeHosting/​ManagedAdapter/​Program.cs Starts the managed adapter process.
playground/​NativeHosting/​CliAppHost/​apphost.mts Defines the CLI compatibility AppHost.
playground/​NativeHosting/​CliAppHost/​aspire.config.json Configures the CLI sample.
playground/​NativeHosting/​CliAppHost/​failing-apphost.mts Exercises AppHost failure handling.
playground/​NativeHosting/​CompatibleAppHost/​apphost.mts Defines the bounded-contract AppHost.
playground/​NativeHosting/​CompatibleAppHost/​failing-apphost.mts Exercises compatibility-path failures.
playground/​NativeHosting/​web/​Dockerfile Builds the Nuxt workload container.
playground/​NativeHosting/​web/​nuxt.config.ts Configures the Nuxt workload.
playground/​NativeHosting/​web/​server/​api/​bridge.get.ts Exercises tunnel forwarding.
playground/​NativeHosting/​web/​server/​api/​health.get.ts Exposes workload health.
playground/​NativeHosting/​web/​server/​api/​redis.get.ts Exercises Redis references.
src/​Aspire.Cli/​Aspire.Cli.csproj Includes shared kubeconfig parsing.
src/​Aspire.Cli/​Backchannel/​NativeAppHostCliBackchannel.cs Adapts native control-plane RPCs to the CLI.
src/​Aspire.Cli/​Commands/​RunCommand.cs Adds native shutdown and state handling.
src/​Aspire.Cli/​Projects/​AppHostServerProject.cs Selects the opt-in native server.
src/​Aspire.Cli/​Projects/​GuestAppHostProject.cs Integrates native launch and backchannel behavior.
src/​Aspire.Cli/​Projects/​NativeAppHostServerProject.cs Launches and prepares the native server.
src/​Aspire.Cli/​Utils/​EnvironmentChecker/​DcpKubeconfig.cs Uses shared kubeconfig parsing.
src/​Shared/​DcpKubeconfigData.cs Parses DCP connection material.
tests/​Aspire.Cli.Tests/​Backchannel/​NativeAppHostCliBackchannelTests.cs Tests native readiness and control forwarding.
tests/​Aspire.Cli.Tests/​Projects/​NativeAppHostServerProjectTests.cs Tests native launch and package restrictions.
tests/​Aspire.Cli.Tests/​TestServices/​FakeAppHostServerSession.cs Supports configurable fake RPC invocation.
tests/​Aspire.Cli.Tests/​Utils/​DcpKubeconfigDataTests.cs Tests kubeconfig scalar parsing.

🧠 Review effort: Balanced

Comment thread src/Aspire.Cli/Commands/RunCommand.cs Resolved
Exercise typed portable data through generated APIs, configure Redis persistence, and document AOT costs and graph lifetime.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Integration-host authentication, concurrent graph mutation, cleanup reliability, and bounded-output issues remain unresolved.

7 open findings
Previously missed (2)

In code that hasn't changed since last review

Medium severity Continue graph cleanup after individual failures

playground/​NativeHosting/​ats-ports.mts:346

Graph cleanup is fail-fast: one rejected monitor task or one failed tunnel deletion aborts releaseGraph, so later session-owned tunnels are never deleted. This is especially likely after a monitor transport failure. Settle monitor tasks and attempt every owned-tunnel deletion before reporting aggregate cleanup failure.

Medium severity Preserve stderr stream and log it as errors

src/​Aspire.Cli/​Backchannel/​NativeAppHostCliBackchannel.cs:91

This discards the captured stream and marks stderr as Information. Native server and DCP failures are intentionally written to stderr, so CLI diagnostic files and extension forwarding will present failures as ordinary output. Preserve stream and map StdErr to LogLevel.Error.

🧠 Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Consolidate the native runtime into one AOT server project with generated ATS dispatch, DCP execution, and a Dashboard protocol adapter. Add server-owned workspaces, staged model revisions, stable resource executions, integration configuration acknowledgements, and ordered workload replacement. Cover actual guest reexecution, retained workloads and data, dependent endpoint rebinding, and cleanup with real CLI and Dashboard E2E fixtures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Implement the existing CLI backchannel on the native server, use source-generated wire DTOs and validated runtime policies, and launch the authenticated Dashboard through DCP. Fix playground composition, connection-material startup retries, integration registration, output bounds, and CI-owned coverage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 5232bd9d-6550-4411-a521-cd6be239f67e
@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot October 11, 2026 03:56
@github-actions

This comment has been minimized.

Keep stop coordination connection-owned and bounded, align C# and TypeScript run lifetimes, and exercise run/start/publish/deploy in the real Compose smoke without changing managed Hosting behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7a6644bf-9352-4988-b790-7b2c407f50c0

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The critical aspire-managed.dll Dashboard launch failure must be fixed and covered by a regression test.

1 open issue

Review effort: Balanced

@github-actions

This comment has been minimized.

Pass the dashboard subcommand for the bundled managed DLL and cover every launch form. Stop the foreground smoke by AppHost PID so project-wide launcher cleanup cannot race its zero-exit assertion; keep project-wide shutdown coverage for detached start.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7a6644bf-9352-4988-b790-7b2c407f50c0
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The broad runtime, RPC, and process-lifecycle changes require final human review.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Use fake cleanup deadlines and DCP-assigned executable ports, snapshot complete publishing and bootstrap artifacts, and refresh native publishing documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a6644bf-9352-4988-b790-7b2c407f50c0
@github-actions

This comment has been minimized.

…hots

Compare the bootstrap fingerprint with the exact embedded contract bytes before normalizing the build-specific identity for Verify.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a6644bf-9352-4988-b790-7b2c407f50c0

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Cross-cutting runtime, RPC, and lifecycle changes require final human review.

No open issues 🎉

Review effort: Balanced

@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Broad native runtime, RPC, and lifecycle changes require final human review.

No open issues 🎉

Review effort: Balanced

@mitchdenny Mitch Denny (mitchdenny) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the six shared compatibility surfaces for existing AppHosts. No concrete legacy regression identified. Final-revision official signing and layout validation remains recommended before merge.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a6644bf-9352-4988-b790-7b2c407f50c0
@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The native runtime, RPC, and CLI integration changes require final human review beyond static analysis.

No open issues 🎉

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Match the other bundled executables after the .NET 11 RC2 update so NativeAOT publish does not attempt to copy a missing XML documentation file.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a6644bf-9352-4988-b790-7b2c407f50c0
@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

Selects the full PR test matrix + all PR-gated jobs (ALL) — a rule matching 'Aspire.slnx' selects ALL


Selection computed for commit 469b9ad.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Broad native-runtime, RPC, and lifecycle changes require final human review and approval.

No open issues 🎉

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #1936

Generated by PR Documentation Check · copilot · auto · 29.7 AIC · ⌖ 1.16 AIC · ⊞ 20.4K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#1936 targeting release/17.0.

Documented the new opt-in features.appHostServerV2 config key in the CLI config settings table. Triggered signals: cli_command_file_changed (ConfigCommand.cs rejects project-only features with --global), new_package_added/new_hosting_integration_project (new Aspire.Hosting.Native.* projects), new_public_type, polyglot_code_generator_changed, target_framework_changed. The PR is draft/experimental, so only the user-visible config surface was documented.

Note

This draft PR needs human review before merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-integrations Issues pertaining to Aspire Integrations packages

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants