microsoft/aspire: a code-first apphost for distributed apps

The wiring problem Aspire targets

A distributed app is mostly a list of relationships: which service talks to which cache, which frontend waits for which API, which endpoint is exposed outside the machine. In most stacks that list lives in scattered places. Docker Compose files, launchSettings.json, environment variables, a README nobody updates. Aspire's answer is to move the list into a single apphost file so the graph is executable rather than documented.

The audience is specific. Teams running several processes at once on a developer machine, plus containers for backing services, plus at least one frontend. The README's own example uses Redis, a Node app and a Vite frontend, which is a fair picture of the intended shape. A single-process web app gains nothing from an apphost, and a team that already has a Compose file it trusts may find the apphost to be a second source of truth.

How the apphost graph becomes a running system

The mechanism is a builder. In the C# form, DistributedApplication.CreateBuilder(args) returns a builder; each Add call registers a resource and returns a handle; each With or WaitFor call on that handle adds an edge. builder.Build().Run() starts the graph. The TypeScript form mirrors it exactly: createBuilder(), then addRedis, addNodeApp, addViteApp, with the same withReference and waitFor methods in camelCase, ending in build().run().

The method names carry real semantics. WithReference(cache) injects the connection information for the cache into the dependent resource. WaitFor(cache) makes startup ordering explicit, so the API does not begin before the cache is ready. WithHttpEndpoint(env: "PORT") binds an HTTP endpoint and passes the port through the named environment variable. WithExternalHttpEndpoints() marks the endpoint as reachable from outside. Those four verbs are the core of the model, and reading them in order tells you what the runtime does.

The repo layout backs this up. Top-level entries include src/, tests/, playground/, benchmarks/ and extension/, and the README states the repo contains the Aspire CLI, the AppHost SDK, the dashboard, service discovery infrastructure, project templates, integrations and a VS Code extension. Observability is described as OpenTelemetry-based, and the developer control plane is a separate repository, microsoft/dcp, linked from the README.

Installing the Aspire CLI and running a first apphost

The README gives two install paths, one per platform family. On Windows it uses PowerShell; on Linux or macOS it pipes a shell script. Both fetch the latest released version, and the README points to docs/using-latest-daily.md if you want daily builds instead.

irm https://aspire.dev/install.ps1 | iex

That is the Windows command. On Linux or macOS the equivalent is:

curl -sSL https://aspire.dev/install.sh | bash

After the CLI is present, a first apphost is a single file. The README's C# sample is the shortest complete definition it gives, and it is worth reading as the canonical shape rather than copying blindly:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var api = builder.AddNodeApp("api", "./api", "src/index.ts")
        .WithReference(cache)
        .WaitFor(cache)
        .WithHttpEndpoint(env: "PORT")
        .WithExternalHttpEndpoints();

builder.AddViteApp("frontend", "./frontend")
    .WithReference(api)
    .WaitFor(api);

builder.Build().Run();

The expected result is that the CLI runs the whole app locally: Redis, the Node API on the port passed through PORT, and the Vite frontend, with the API waiting on the cache and the frontend waiting on the API. The README states the CLI exposes OpenTelemetry-based observability, so the dashboard is where you would look for traces. The repo also ships run-aspire.sh and run-aspire.cmd at the top level, which are the in-repo entry points rather than the published CLI.

The README does not document rollback, uninstall steps or how the install scripts behave behind a proxy. If those matter, treat them as unverified.

Where the model gets in the way

The apphost is code, which means it is a program you maintain. Every new service is a new Add call, every new dependency a new WithReference, and the ordering constraints have to be stated rather than inferred. For a team that adds services weekly, that is a small tax paid in a language they already know. For a team that treats local orchestration as infrastructure owned by someone else, it is a second configuration surface that can drift from the deployment manifests.

Two constraints stand out in the README. First, the note on containers: the Aspire team states it cannot evaluate the underlying third-party containers for which it provides API support, and the README tells you to evaluate whichever containers you compose and automate against your own security, safety, cryptographic and regulatory requirements. That is a direct statement that the integration API is not a security review. Second, the multi-language claim is narrower than it sounds. The README shows C# and TypeScript apphosts, and the repository contains pyrightconfig.json, but the README does not document a Python apphost form, so do not assume parity across languages.

The wrong-tool case is a single service with one database. You would write an apphost, run it, and get a dashboard for a process you could have started with one command.

Aspire and Docker Compose: different sources of truth

Docker Compose is the obvious comparison, and the difference is not features. Compose describes containers in YAML and is consumed by the Docker engine. Aspire describes resources in a host language and is consumed by the Aspire CLI, which may start containers for some resources and local processes for others. A Node app in the README sample is a local process, not necessarily an image; Compose would want a Dockerfile for it.

That distinction decides the choice. If your local environment is already container-shaped and your team is fluent in Compose, Aspire adds a layer above it without removing it. If your pain is that half your services run as processes and half as containers, and the handoffs between them are implicit, the apphost expresses those handoffs directly through WithReference and WaitFor. Compose has depends_on, but it does not inject a connection string into an application the way a resource reference does. The trade is that Compose files are portable to any machine with Docker, while an apphost requires the Aspire CLI and the SDK.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-25. Releases in the same period include v13.5.3 on 2026-08-25, v13.5.2 on 2026-08-21 and v13.5.1 on 2026-08-21, so the project is being released frequently. The README offers daily builds through docs/using-latest-daily.md, which is the upgrade channel to understand before you pin anything: the install scripts fetch the latest released version by default, so a fresh install is not automatically a pinned install.

The licence is MIT for the code in the repo, stated in the README and present as LICENSE.TXT at the top level. MIT is permissive, but it says nothing about the containers your apphost pulls in. The README's own note puts that responsibility on you, and there is a THIRD-PARTY-NOTICES.TXT in the repository root if you need to enumerate what ships alongside. Nothing here is legal advice; if your organisation has container provenance rules, the README's note is the sentence to bring to that conversation.

Editorial conclusion

Adopt Aspire if you already run a multi-service app locally and want the wiring (Redis, Node apps, Vite frontends, HTTP endpoints) expressed in one apphost file in C# or TypeScript, with a dashboard and OpenTelemetry traces attached. Skip it if your stack is a single process, or if your team will not maintain the apphost as code that changes with every new service. Before committing, check the install scripts at aspire.dev and the docs/using-latest-daily.md note if you intend to pin daily builds, and read the README's warning that the Aspire team cannot evaluate the third-party containers its integrations compose.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes