[MS] Running Multiple Instances of an Aspire AppHost Without Port Conflicts - devamazonaws.blogspot.com

Running two different Aspire AppHosts at the same time works fine — they each get their own ports. But what if you need to run multiple instances of the same AppHost? Maybe you've cloned your source code into two different directories, or you're using git worktrees and want to work with both at the same time. That fails with port conflicts.

If you're running integration tests alongside development, or working with AI agents that spin up multiple Aspire instances from the same project, you've hit this problem too.

Aspire 13.2 solves this with isolated mode—a new flag that assigns random ports and separate configuration to each run.

The Problem: Port Collisions in Parallel Development

By default, Aspire runs services on predictable ports. When you start an AppHost:

aspire run

It binds to specific ports defined in your dashboard config. If you have two instances of an Aspire project open and try to run both, the second one fails:

Error: Port 17370 is already in use by another application

This blocks common development scenarios:

• Working across multiple checkouts: You've cloned the same repo into two directories (or are using git worktrees) and need to run the AppHost from both at the same time.
• Integration tests: You want to run tests against a live AppHost while continuing to develop.
• AI-assisted development: Agents spinning up multiple Aspire instances to test different configurations.

The workaround was tedious: manually reassign ports, manage environment variables, or restart everything to switch projects.

The Solution: Isolated Mode

Aspire 13.2 introduces the --isolated option to aspire run and aspire start. This CLI option does two things:

1. Assigns random ports — Each instance gets its own port range, eliminating collisions.
2. Creates isolated user secrets — Configuration stays separate, preventing cross-instance contamination.

Run it:

aspire run --isolated

That's it. No manual port configuration. No environment variable juggling. Each run gets a fresh, collision-free environment.

Real Scenarios

Scenario 1: Working Across Multiple Checkouts

You've cloned the same repo into two directories — maybe one for a feature branch and another for a bug fix. Start the AppHost from the first checkout:

cd ~/projects/my-app-feature
aspire run --isolated

In another terminal, start the same AppHost from the second checkout:

cd ~/projects/my-app-bugfix
aspire run --isolated

Both run without conflicts. Each gets randomized ports. The dashboard still shows you what's running and where, but you're not fighting over the same ports.

Scenario 2: Background Agents in VS Code Copilot Chat

When you use Copilot Chat's background agent in VS Code, it automatically creates a git worktree in a separate directory so it can work on your code without interfering with your current session. If your project includes an Aspire AppHost, the agent may need to run it — but you're already running the same AppHost in your primary worktree. Without isolated mode, this causes a port collision.

With --isolated, both instances just work:

• Your main worktree: aspire run --isolated in your current checkout
• The background agent's worktree: aspire run --isolated in the auto-created worktree

Each gets its own ports and secrets. You keep developing while the agent builds, tests, and iterates — all against the same AppHost, without conflicts.

The Aspire skill that's setup with aspire agent init instructs agents to use --isolated when using git worktrees. The Copilot agent should run your Aspire AppHost with isolation automatically.

How It Works Under the Hood

Isolated mode randomizes the port range assigned to your services. Instead of Services being at ports 8080, 8081, 8082, one run might get 15234, 15235, 15236, and another gets 22891, 22892, 22893.

The dashboard and configuration automatically adjust. Your code doesn't need changes — Aspire handles the mapping.

User secrets are also isolated per run. If you have different environment variables or API keys configured, each isolated instance keeps its own copy, preventing cross-project leaks.

When to Use Isolated Mode

Use it when:

• Running multiple instances of the same AppHost simultaneously
• Testing integration scenarios with a live AppHost while continuing to develop
• Running automated tests that need dedicated ports
• Working with tools or agents that spawn multiple instances of the same project
• Using git worktrees or multiple checkouts of the same repo

You can still use the standard aspire run for single-project development if you prefer predictable ports.

Get Involved

• 📖 Learn more: Read the full documentation on Aspire CLI at aspire.dev.
• 💬 Give us feedback: We'd love to hear what you think — file issues or join discussions on the Aspire GitHub repo.
• 🌐 Join the community: Follow us and connect with other Aspire developers at aspire.dev/community.

Post Updated on April 9, 2026 at 06:00PM
Thanks for reading
from devamazonaws.blogspot.com