From b5d05cd18655af1ef37a9790f516f6ea1590f22c Mon Sep 17 00:00:00 2001 From: guru-bharadwaj20 Date: Fri, 20 Nov 2026 09:11:33 +0530 Subject: [PATCH 1/2] Clarify what --isolated allows for aspire run and aspire start The option text said --isolated lets multiple instances of the same AppHost run at once. The CLI stops an instance that is already running from the same AppHost path, isolated or not, so concurrent runs need separate directories such as Git worktrees. Spell that out and replace the examples with a worktree example. Fixes #2184 --- .../docs/reference/cli/commands/aspire-run.mdx | 14 ++++++++++++-- .../docs/reference/cli/commands/aspire-start.mdx | 9 +++++++-- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx index e969855382..a5389f5e81 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx @@ -107,7 +107,9 @@ The following options are available: - **`--isolated`** - Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. This is useful for parallel testing or comparing different configurations side-by-side. + Run with randomized ports and isolated user secrets, allowing copies of the same AppHost in different directories, such as separate Git worktrees, to run simultaneously. This is useful for parallel testing or comparing different configurations side-by-side. + + This doesn't enable multiple concurrent instances from the same AppHost path. If an instance of the AppHost is already running from that path, `aspire run` stops it before starting the new one, with or without `--isolated`. `aspire run`, `aspire run --detach`, and `aspire start` all behave this way. When it stops an instance this way, `aspire run --isolated` also prints a warning that suggests running from a different directory. - **`--no-build`** @@ -159,9 +161,17 @@ The following options are available: aspire run --detach --format Json ``` -- Run in isolated mode for parallel testing: +- Run two copies of the same AppHost side by side, the second one from a Git worktree. In the repository's main checkout: + + ```bash title="Aspire CLI" + git worktree add ../my-app-feature + aspire run --isolated + ``` + + Then, in a second terminal: ```bash title="Aspire CLI" + cd ../my-app-feature aspire run --isolated ``` diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx index 0fcf36f806..ba9e496320 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx @@ -105,7 +105,9 @@ The following options are available: - **`--isolated`** - Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances of the same AppHost to run simultaneously. + Run with randomized ports and isolated user secrets, allowing copies of the same AppHost in different directories, such as separate Git worktrees, to run simultaneously. + + This doesn't enable multiple concurrent instances from the same AppHost path. If an instance of the AppHost is already running from that path, `aspire start` stops it before starting the new one, with or without `--isolated`. `aspire run`, `aspire run --detach`, and `aspire start` all behave this way. - @@ -139,10 +141,13 @@ The following options are available: aspire start --format Json ``` -- Start the AppHost in isolated mode: +- Start two copies of the same AppHost side by side, the second one from a Git worktree: ```bash title="Aspire CLI" aspire start --isolated + git worktree add ../my-app-feature + cd ../my-app-feature + aspire start --isolated ``` - Start the AppHost with a specific environment: From 2e8bbf85eb8550107ec62e88e558459def2d1cbc Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Fri, 20 Nov 2026 07:27:26 -0600 Subject: [PATCH 2/2] Clarify --isolated warning scope and worktree examples - Note that only aspire run --isolated without --detach prints the stop warning. - Say that a worktree contains only committed files. - Say where the second terminal and the aspire start example begin. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/reference/cli/commands/aspire-run.mdx | 6 +++--- .../content/docs/reference/cli/commands/aspire-start.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx index a5389f5e81..64c3d1f24e 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-run.mdx @@ -109,7 +109,7 @@ The following options are available: Run with randomized ports and isolated user secrets, allowing copies of the same AppHost in different directories, such as separate Git worktrees, to run simultaneously. This is useful for parallel testing or comparing different configurations side-by-side. - This doesn't enable multiple concurrent instances from the same AppHost path. If an instance of the AppHost is already running from that path, `aspire run` stops it before starting the new one, with or without `--isolated`. `aspire run`, `aspire run --detach`, and `aspire start` all behave this way. When it stops an instance this way, `aspire run --isolated` also prints a warning that suggests running from a different directory. + This doesn't enable multiple concurrent instances from the same AppHost path. If an instance of the AppHost is already running from that path, `aspire run` stops it before starting the new one, with or without `--isolated`. `aspire run`, `aspire run --detach`, and `aspire start` all behave this way. When it stops an instance this way, `aspire run --isolated` without `--detach` also prints a warning that suggests running from a different directory. - **`--no-build`** @@ -161,14 +161,14 @@ The following options are available: aspire run --detach --format Json ``` -- Run two copies of the same AppHost side by side, the second one from a Git worktree. In the repository's main checkout: +- Run two copies of the same AppHost side by side, the second one from a Git worktree. A worktree contains only committed files, so commit your changes before you create it. In the repository's main checkout: ```bash title="Aspire CLI" git worktree add ../my-app-feature aspire run --isolated ``` - Then, in a second terminal: + Then, in a second terminal opened in the main checkout: ```bash title="Aspire CLI" cd ../my-app-feature diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx index ba9e496320..54eb53207e 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-start.mdx @@ -141,7 +141,7 @@ The following options are available: aspire start --format Json ``` -- Start two copies of the same AppHost side by side, the second one from a Git worktree: +- Start two copies of the same AppHost side by side, the second one from a Git worktree. A worktree contains only committed files, so commit your changes before you create it. From the repository's main checkout: ```bash title="Aspire CLI" aspire start --isolated