Add Aspire to the app you already have instead of rebuilding your solution around a new template. The fastest path is aspire init paired with an AI coding agent that automatically discovers your services and wires them into an AppHost. If you prefer full control, manual steps are provided below.
As distributed applications grow, local development often turns into a collection of fragile scripts, copied connection strings, and startup-order tribal knowledge. Aspire gives you a single orchestration layer for the resources you already own. Define the relationships once in code, and Aspire handles service discovery, configuration injection, startup ordering, and dashboard visibility.
You can also adopt Aspire incrementally. Start by modeling the parts that are hardest to keep aligned by hand, such as containers, databases, caches, queues, background workers, and local dev commands. Add telemetry when you’re ready, then deepen the model as your app grows.
The fastest way to add Aspire to an existing app is to let aspire init scaffold the skeleton, then hand off wiring to the aspireify agent skill. The skill handles resource discovery, dependency wiring, OpenTelemetry setup, and validation automatically.
Run aspire init in your repo root:
Initialize Aspire
aspireinit
Choose your AppHost language (C# or TypeScript) when prompted, or pass --language csharp / --language typescript. The command creates a minimal AppHost, an aspire.config.json, and installs the aspireify skill into your agent’s skill directory. For existing JavaScript or TypeScript apps with a root package.json, the TypeScript AppHost is created in an aspire-apphost/ subfolder so Aspire doesn’t change the existing app package’s module settings.
Ask your AI coding agent to run the aspireify skill. The agent will:
Scan your repo and discover existing projects, services, containers, and infrastructure
Ask you to confirm the resources it found, which ones you want included, and other clarifying questions before starting
Wire resources into the AppHost with WithReference, WaitFor, endpoints, and volumes
Add ServiceDefaults and configure OpenTelemetry for each service
Validate the setup by running aspire start
Once the agent reports success, run aspire start yourself and open the dashboard to verify everything looks correct. Something not right? Tell the agent-it has plenty of tools from Aspire to troubleshoot!
For more details on the aspire init command and the aspireify skill, see the CLI reference: aspire init.
If you prefer full control over the wiring, or want to understand what the aspireify skill does under the hood, follow the manual steps below. This is also the reference for anyone extending or customizing an AppHost after the initial setup.
Use a TypeScript AppHost when your repo already centers on a Node.js workspace or when you prefer path-based orchestration in TypeScript.
Lives in apphost.mts; for existing JavaScript and TypeScript apps, aspire init creates it under aspire-apphost/
Runs under supported package managers including npm, pnpm, Yarn 4+, and Bun
Fits naturally into existing package-manager and monorepo workflows
Aspire offers two C# AppHost styles:
File-based AppHost — a single apphost.cs file that uses #:sdk and #:package directives. No .csproj, no solution integration required. Best for repos with polyglot code or quick setups.
Project-based AppHost — a traditional AppHost.csproj that lives inside a .sln alongside your other C# projects. Uses ProjectReference items and the generated Projects namespace for strongly-typed AddProject<T>() calls. Best when your repo is already a .NET solution and you want IDE-integrated orchestration.
Both styles use the same Aspire.AppHost.Sdk and the same hosting APIs.
When your app already lives inside a subdirectory of a larger workspace (for example, apps/my-app/), run aspire init from that subdirectory. The CLI places the AppHost under aspire-apphost/ relative to where you run the command:
The AppHost package and your guest apps can use different package managers. The AppHost directory takes precedence for running AppHost scripts — if the AppHost’s package.json declares "packageManager": "pnpm@..." or contains a pnpm-lock.yaml, pnpm is used for AppHost operations regardless of the toolchain in the parent workspace.
Use a file-based AppHost when you want a lightweight single-file orchestrator without adding a project to your solution. This is the default style created by aspire init when no .sln is detected.
Run aspire init from your repo root. Without a .sln present, it creates a file-based apphost.cs:
Initialize Aspire with a file-based AppHost
aspireinit
Add hosting integrations:
Add hosting integrations
aspireaddredis
Wire the resources in apphost.cs:
apphost.cs
#:sdk Aspire.AppHost.Sdk@13.5.3
#:package Aspire.Hosting.Redis@13.5.3
#pragmawarningdisable ASPIRECSHARPAPPS001
var builder =DistributedApplication.CreateBuilder(args);
var cache =builder.AddRedis("cache");
var api =builder.AddCSharpApp("api","./src/Api/MyApp.Api.csproj")
.WithReference(cache)
.WithHttpHealthCheck("/health");
var worker =builder.AddCSharpApp("worker","./src/Worker/MyApp.Worker.csproj")
.WithReference(cache);
builder.Build().Run();
After setup, a typical repo layout looks like this:
Use this approach when your repo is already a .NET solution (.sln or .slnx) with multiple projects. The project-based AppHost uses ProjectReference items and the generated Projects namespace for strongly-typed AddProject<T>() calls, giving you full IDE support including IntelliSense, refactoring, and build-order awareness.
Run aspire init from your solution root. It detects the .sln and creates a project-based AppHost automatically:
Initialize Aspire in a .NET solution
aspireinit
Add project references from the AppHost to each service you want to orchestrate:
Use this approach when Aspire already has a first-class resource type for the workload you want to run. That keeps the application model focused on what the service is and what it depends on, instead of reducing it to a generic shell command.
Common examples include Node.js apps, Vite frontends, Python workers, and Uvicorn-based APIs.
apphost.cs — Existing services with hosting integrations
#:sdk Aspire.AppHost.Sdk@13.5.3
#:package Aspire.Hosting.Redis@13.5.3
#:package Aspire.Hosting.Python@13.5.3
#:package Aspire.Hosting.JavaScript@13.5.3
var builder =DistributedApplication.CreateBuilder(args);
var cache =builder.AddRedis("cache");
var api =builder.AddUvicornApp("api","../services/api","main:app")
.WithUv()
.WithReference(cache)
.WithExternalHttpEndpoints();
var worker =builder.AddPythonApp("worker","../workers/inventory-sync","worker.py")
.WithReference(cache);
var web =builder.AddViteApp("web","../services/web")
.WithReference(api)
.WaitFor(api);
builder.Build().Run();
If a workload does not have a dedicated hosting API yet, model it as an executable resource with AddExecutable or addExecutable so it can still participate in the same application model.
Use this approach when the important boundary is the runtime environment itself: a published container image, a shared database, a cache, a queue, or an existing infrastructure topology. Model the shared resources first, then attach the workloads that consume them so connectivity, configuration, and startup order are explicit.
When Aspire has a first-class integration for that infrastructure, add it first:
Use this scenario when Docker Compose already captures the shape of your system. Treat the Compose file as a map of workloads, shared infrastructure, exposed ports, and dependency edges that you want to restate in the AppHost.
The goal is not a line-by-line translation of every field, but a clearer resource model of the same relationships.
These scenarios are starting points, not mutually exclusive modes. Most real apps mix workload-specific resources, containers, shared infrastructure, project-path references, and occasional custom commands in a single application model. The key is that dependencies, endpoints, configuration, and startup behavior become explicit.
Telemetry is configured inside the workloads that emit it, not in the AppHost itself. Aspire gives those workloads an OTLP destination and a shared dashboard during local orchestration, but each service still uses the observability libraries that fit its runtime.
For other runtimes, use the OpenTelemetry SDK or instrumentation library that matches the runtime you are already using, then export telemetry to the OTLP endpoint Aspire provides during local orchestration.
At this point, you have the core workflow: describe the resources your app needs, connect the workloads that depend on them, and let Aspire run the system together during local development. From there, you can deepen the setup incrementally instead of trying to remodel the entire app at once.
Learn more about Executable resources for custom commands and non-project workloads
Aspire