Running multiple instances of the same source code in parallel is increasingly common — especially with agentic development. Tools like VS Code Copilot’s background agent create git worktrees to work on your code independently, AI agents spin up separate environments to test different approaches, and developers use multiple checkouts to work across feature branches simultaneously.

This creates a fundamental problem: applications bind to specific ports, and two instances of the same app fight over the same ones. The second instance fails with a port conflict. You’re stuck manually reassigning ports, juggling environment variables, or shutting things down to switch contexts.

Aspire 13.2 solves this with isolated mode — a new --isolated flag that gives each run its own random ports and separate configuration, so multiple instances of the same AppHost just work.

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 set up 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

When you pass --isolated, the CLI generates a unique instance ID for the run. This ID drives two key behaviors:

Randomized Ports

Instead of binding to the predictable ports defined in your AppHost configuration, isolated mode selects random available ports for both the dashboard and all service endpoints. Where a normal run might bind services to ports 8080, 8081, and 8082, one isolated run might get 15234, 15235, and 15236 while another gets 22891, 22892, and 22893.

The dashboard and service discovery automatically adjust — your code doesn’t need changes. Aspire’s service discovery resolves endpoints at runtime, so services find each other regardless of which ports they land on.

Isolated User Secrets

Each isolated run gets its own user secrets store, keyed by the instance ID. This means connection strings, API keys, and other configuration don’t leak between instances. If you’re testing with different Azure resources or database connections across two worktrees, each stays self-contained.

The isolated secrets are stored alongside your normal user secrets but under a separate key, so they don’t interfere with your standard aspire run configuration.

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 Started

• 📖 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.