Add Aspire to an existing app

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.

Before you begin, make sure you have:

• Aspire CLI installed
• An existing application or workspace to add Aspire to
• The runtimes and tools your existing services already need

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.

1. Run aspire init in your repo root:

   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.

2. 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

3. 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!

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.

The AppHost is the orchestration layer. Your choice here changes how you express orchestration, not what Aspire can 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.

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:

aspireaddpostgres
aspireaddredis

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.

Once the AppHost captures the resources and relationships you care about, start everything together with the Aspire CLI.

1. From the directory that contains your AppHost, run:

   aspirerun

2. Wait for the CLI to discover the AppHost, launch the resources, and print the dashboard URL.

   Findingapphosts...
   Dashboard:https://localhost:17068/login?t=example
   PressCTRL+Ctostoptheapphostandexit.

3. Open the dashboard in your browser and verify:

   • All resources start successfully
   • Service dependencies appear in the expected order
   • Logs, traces, and metrics are visible
   • Endpoints and environment variables look correct

4. Exercise the actual app flows you care about, such as frontend-to-API calls, worker jobs, or database access.

5. Stop the system by pressing in your terminal.

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
• Follow Deploy your first app when you are ready to move beyond local orchestration
• Use the Aspire extension for VS Code to run and inspect your app from the editor
• Check the Troubleshooting guide for common setup issues
• Ask questions and share feedback on Discord