Astro dev runs in the background when an AI agent is detected
- Astro
When Astro detects an AI agent, astro dev runs as a background process. Since v7.2.0, astro preview runs in the background too. The server does not block the agent’s terminal, so the agent keeps working.
This mode applies on macOS and Linux. On Windows, the server stays in the foreground.
Astro records the server in .astro/dev.json. The file holds the server’s URL, port, and PID.
In this mode, the astro dev command exits right away, but the server keeps running. A tool that waits for that command, such as Playwright’s webServer, can misread its state.
Managing the background server
These commands manage the background server:
pnpm astro dev statusshows the URL, PID, and uptime.pnpm astro dev logsprints the logs. This command works only for a server started in the background. Add--followto stream new lines.pnpm astro dev stopsends SIGTERM and waits up to 5 seconds. If the server is still running, Astro sends SIGKILL.
The dev server also exposes the /_astro/status endpoint, which returns {"ok": true}. Agents and tools can use it to check whether the server is ready to accept requests.
The --ignore-lock flag
The --ignore-lock flag skips the lock file check and write. A new server can run alongside one that is already running. stop, status, and logs do not track the new server.
In Astro 7.4.11, this flag also turns off automatic background mode. The server stays in the foreground.
Combining it with --background or --force makes Astro reject the command with an error.
In this site’s repo
Playwright in this repo runs astro dev --ignore-lock through its webServer setting. The flag keeps the server in the foreground until Playwright stops it with SIGTERM.
To run astro dev yourself in the foreground, add ASTRO_DEV_BACKGROUND=0 before the command. Playwright does not need this variable.
env ASTRO_DEV_BACKGROUND=0 pnpm astro devAstro still records the server as background in .astro/dev.json, so status labels it background. logs fails with No log file found., or prints an older log if an earlier background server left .astro/dev.log.
