diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx
index 5763d582929f9..caa15ed7bdd35 100644
--- a/src/content/docs/en/guides/build-with-ai.mdx
+++ b/src/content/docs/en/guides/build-with-ai.mdx
@@ -362,19 +362,20 @@ The same technology that powers Astro's MCP server is also available as a chatbo
-When an AI coding agent is detected, `astro dev` automatically starts the dev server as a detached background process. This prevents the dev server from blocking the agent's terminal and allows it to continue working while the server runs.
+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.
-A lock file (`.astro/dev.json`) is written when the dev server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project.
+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.
-If you are not using an AI coding agent, `astro dev` starts in the foreground process and logs to the terminal.
+If you are not using an AI coding agent, the server starts in the foreground process and logs to the terminal.
-To opt out of automatic background mode, set the `ASTRO_DEV_BACKGROUND` environment variable before running `astro dev`:
+To opt out of automatic background mode, set the `ASTRO_DEV_BACKGROUND` or `ASTRO_PREVIEW_BACKGROUND` environment variable before running the command:
```shell
ASTRO_DEV_BACKGROUND=0 astro dev
+ASTRO_PREVIEW_BACKGROUND=0 astro preview
```
-See the [CLI reference](/en/reference/cli-reference/#astro-dev) for the full list of `astro dev` flags and subcommands.
+See the CLI reference for the full list of flags and subcommands for [`astro dev`](/en/reference/cli-reference/#astro-dev) and [`astro preview`](/en/reference/cli-reference/#astro-preview).
### Health endpoint
diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx
index ecfffc301923a..cada6e11c5032 100644
--- a/src/content/docs/en/reference/adapter-reference.mdx
+++ b/src/content/docs/en/reference/adapter-reference.mdx
@@ -1039,7 +1039,7 @@ Describes the function an adapter should export to start a preview server when [
-**Type:** `{ host?: string; port: number; closed(): Promise; stop(): Promise; }`
+**Type:** `{ host?: string; port: number; urls?: { local: string[]; network: string[] }; closed(): Promise; stop(): Promise; }`
Describes an instance of a preview server for the adapter.
@@ -1062,6 +1062,16 @@ Defines the host the preview server is listening on.
Defines the port the preview server is listening on.
+#### `PreviewServer.urls`
+
+
+
+**Type:** `{ local: string[]; network: string[] } | undefined`
+
+
+
+Defines the resolved URLs the preview server is listening on, grouped into `local` (loopback addresses) and `network` (LAN and public addresses). Astro uses these to record the server's address in the lock file [when the preview server runs in the background](/en/reference/cli-reference/#--background).
+
#### `PreviewServer.closed()`
diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx
index 803270fad5c5c..98442f1ecac00 100644
--- a/src/content/docs/en/reference/cli-reference.mdx
+++ b/src/content/docs/en/reference/cli-reference.mdx
@@ -202,22 +202,6 @@ The following hotkeys can be used in the terminal where the Astro development se
The command accepts [common flags](#common-flags) and the following additional flags.
-#### `--background`
-
-Starts the dev server as a detached background process and enables [JSON logging](#--json). This flag is provided automatically when an AI agent is detected. You can also use it manually:
-
-```shell
-astro dev --background
-```
-
-If a server is already running for the project, the command prints the existing server's info and exits without starting a new one. Use the `--force` flag to stop the existing server and start a new one.
-
-```shell
-astro dev --background --force
-```
-
-See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint.
-
#### `--ignore-lock`
@@ -228,32 +212,10 @@ Starts the dev server without checking or writing the lock file used to detect o
astro dev --ignore-lock --port 4322
```
-The new server is not tracked by `astro dev stop`, `astro dev status`, or `astro dev logs`.
+The new server is not tracked by the [`stop`, `status`, or `logs` subcommands](#common-subcommands).
When combined with `--background` (including when triggered by an AI coding agent) or `--force`, an error is thrown, as both rely on the lock file.
-Subcommands
-
-
-
-#### `astro dev stop`
-
-Stops a running background dev server. Sends `SIGTERM` and waits up to 5 seconds for the server to exit gracefully. If the process is still running after that, it escalates to `SIGKILL`.
-
-#### `astro dev status`
-
-Checks whether a background dev server is running and displays its URL, PID, and uptime.
-
-#### `astro dev logs`
-
-Displays logs from a background dev server. Only works when the server was started with `astro dev --background`, since foreground servers write logs directly to the terminal.
-
-##### Flags
-
-###### `--follow` (`-f`)
-
-Streams new log output as it's written, similar to `tail -f`. Without this flag, the current log file contents are printed and the command exits.
-
## `astro build`
Builds your site for deployment. By default, this will generate static files and place them in a `dist/` directory. If any routes are [rendered on demand](/en/guides/on-demand-rendering/), this will generate the necessary server files to serve your site.
@@ -278,7 +240,7 @@ The following hotkeys can be used in the terminal where the Astro preview server
- `o` + `enter` to open your Astro site in the browser.
- `q` + `enter` to quit the preview server.
-The `astro preview` command can be combined with the [common flags](#common-flags) documented below to further control the preview experience.
+The `astro preview` command can be combined with the [common flags](#common-flags) documented below to further control the preview experience. Since v7.2.0, it also accepts the [`--background` flag](#--background) and the [`stop`, `status`, and `logs` subcommands](#common-subcommands) to manage a background preview server.
## `astro check`
@@ -463,6 +425,30 @@ astro create-key
Set this key as the `ASTRO_KEY` environment variable (e.g. in a `.env` file) and include it in your CI/CD or host’s build settings when you need [a constant encryption key for your server islands](/en/guides/server-islands/#reusing-the-encryption-key) for situations like rolling deployments, multi-region hosting or a CDN that caches pages containing server islands.
+## Common subcommands
+
+
+
+The commands [`astro dev`](#astro-dev) and, since version v7.2.0, [`astro preview`](#astro-preview) accept the following subcommands to manage a [background server](#--background).
+
+### `stop`
+
+Stops a running background server. Sends `SIGTERM` and waits up to 5 seconds for the server to exit gracefully. If the process is still running after that, it escalates to `SIGKILL`.
+
+### `status`
+
+Checks whether a background server is running and displays its URL, PID, and uptime.
+
+### `logs`
+
+Displays logs from a background server. Only works when the server was started with the [`--background` flag](#--background), since foreground servers write logs directly to the terminal.
+
+#### Flags
+
+##### `--follow` (`-f`)
+
+Streams new log output as it's written, similar to `tail -f`. Without this flag, the current log file contents are printed and the command exits.
+
## Common flags
### `--root `
@@ -546,6 +532,28 @@ Enables silent logging, which will run the server without any console output.
Automatically opens the app in the browser on server start. Can be passed a full URL string (e.g. `--open http://example.com`) or a pathname (e.g. `--open /about`) to specify the URL to open.
+### `--background`
+
+
+
+Starts the dev server, or the preview server since v7.2.0, as a detached background process and enables [JSON logging](#--json).
+
+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:
+
+```shell
+astro dev --background
+```
+
+If a server is already running for the project, the command prints the existing server's info and exits without starting a new one. Use the `--force` flag to stop the existing server and start a new one.
+
+```shell
+astro dev --background --force
+```
+
+See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint.
+
### `--json`