Skip to content

Clarify auto-backgrounding on servers inside of agents. #14573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
matthewp wants to merge 5 commits into
base: main
Choose a base branch
from
+4 −2
Open

Clarify auto-backgrounding on servers inside of agents. #14573

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
71bbcff
docs: clarify auto-background does not happen on Windows
matthewp Sep 17, 2026
d356158
docs: drop Windows Job Objects implementation detail from background …
matthewp Sep 17, 2026
b62b74f
Update src/content/docs/en/guides/build-with-ai.mdx
matthewp Sep 17, 2026
e564aea
Update src/content/docs/en/guides/build-with-ai.mdx
matthewp Sep 17, 2026
ff8d9fa
Merge branch 'main' into docs/background-windows
matthewp Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/content/docs/en/guides/build-with-ai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,9 @@ The same technology that powers Astro's MCP server is also available as a chatbo

<p><Since v="7.0.0" /></p>

When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs.
When an AI coding agent is detected on macOS and Linux, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs.

On Windows, or without an AI coding agent, the server starts in the foreground and logs to the terminal. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background).

A lock file (`.astro/dev.json` or `.astro/preview.json`) is written when the server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project.

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/en/reference/cli-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -522,7 +522,7 @@ Starts the dev server, or the preview server since v7.2.0, as a detached backgro

When the server starts, Astro writes a lock file (`.astro/dev.json` or `.astro/preview.json`) to record the server's URL, port, and PID. This avoids launching many instances of the server for the same project.

This flag is provided automatically when an AI agent is detected. You can also use it manually:
This flag is provided automatically when an AI agent is detected on macOS and Linux. On Windows, automatic backgrounding does not happen: when an AI agent is detected, the server stays in the foreground so the agent can manage the process directly. On all platforms, you can also use the flag manually:

```shell
astro dev --background
Expand Down