This post is for developers who let a coding agent start astro dev on their Astro site. It explains how Astro decides an agent is at the keyboard, what background mode then does, how to turn it off, and what Astro 7.4.5 fixed in the lock file that tracks the server. Nothing was run for this post: the Astro changelog, docs, source code at the 7.4.5 tag, one pull request, one bug report and the detection library were read on 2026-11-03, and all release times are UTC.
Astro asks a small library whether an agent is running it
Everything else depends on this check. Astro is “the web framework for content-driven websites.” Its agent check in src/cli/agent.ts calls detectAgenticEnvironment() from am-i-vibing, a library by Matt Kane that lets CLI tools detect when an AI agent is running them. Astro 7.4.5 depends on am-i-vibing ^0.5.0, according to its package.json.
The library sorts environments into three types: agent, interactive and hybrid. By default it consults environment variables only, and Astro calls it with no options. In the 0.5.0 provider list, Claude Code is matched by CLAUDECODE, Gemini CLI by GEMINI_CLI=1 and Codex by CODEX_THREAD_ID. Warp Terminal, matched by TERM_PROGRAM=WarpTerminal, is type hybrid.
Astro accepts only the agent type, because a hybrid environment such as Warp “may not actually be running an AI agent,” as the source comment puts it. That rule came from 7.0.1, which the changelog says fixed astro dev starting in background mode for Warp users. The am-i-vibing README warns of false positives, such as a person typing in a terminal an AI tool opened.
An agent’s dev server runs detached and is tracked by a lock file
Once an agent is detected, the server stops blocking the agent’s terminal. Since 7.0.0, released 2026-06-22 per npm, astro dev starts as a detached background process on macOS and Linux (Windows differs, below); the changelog says this keeps it from blocking the agent. astro preview gained the same behaviour in 7.2.0, released 2026-08-06.
On start, Astro writes a lock file, .astro/dev.json or .astro/preview.json, recording the server’s URL, port and PID, as the Build with AI guide describes. The lock file exists to stop duplicate servers for the same project. The 7.0.0 changelog also lists three subcommands: astro dev status shows URL, PID and uptime, astro dev logs shows output (-f follows it), and astro dev stop ends the server.
The CLI reference says stop sends SIGTERM, waits up to 5 seconds, then escalates to SIGKILL. The dev command source also switches output to JSON when an agent is detected.
On Windows an agent’s server stays in the foreground
Windows behaves differently, so one agent setup can act two ways. Since 7.3.4, released 2026-09-22, an agent-detected astro dev or astro preview on Windows runs in the foreground, according to the changelog. The CLI reference says the agent then manages the process directly, and --background still requests a background server.
Of the sources read, the technical cause appears only in a source comment: detached children “remain in agent-owned Windows Job Objects and are terminated with them.”
How to turn background mode off or run a second server
Turning auto-background off takes one environment variable per command. The Build with AI guide names two environment variables for that, ASTRO_DEV_BACKGROUND and ASTRO_PREVIEW_BACKGROUND, with this example:
ASTRO_DEV_BACKGROUND=0 astro devThe guide and the changelog give only 0 as a value. In the 7.4.5 source, the check is !process.env.ASTRO_DEV_BACKGROUND && isRunByAgent(), so any non-empty value, including 1, skips agent detection.
When a background server is already running for the project, a new astro dev prints the existing server’s info and exits, per the CLI reference. --force stops that server and starts a new one; the CLI help also lists --force as clearing the content layer cache. --ignore-lock starts a server without checking or writing the lock file, and the subcommands do not track that server.
The changelog dates --ignore-lock to 7.1.0 for dev and 7.3.0 for preview. Since 7.3.3, --ignore-lock in an agent environment starts a foreground server instead of erroring. An explicit --background with --ignore-lock still errors, and the dev command source rejects --force with --ignore-lock: “Choose one.”
Before 7.4.5 a status check could orphan a running server
This is the bug that made a server run while Astro lost track of it. Astro checks whether the PID in the lock file is alive with process.kill(pid, 0). Pull request #18558, the fix that shipped in 7.4.5, explains two errors that call can throw: EPERM means the process exists but the caller may not signal it, as when another user or a restricted sandbox runs astro dev status. ESRCH means the process is gone.
Before the fix, the check returned false for every error. A healthy server seen from a sandbox therefore looked dead, and Astro deleted its .astro/dev.json or preview.json. The PR says this “left the server orphaned and untrackable by astro dev stop.” Now EPERM counts as alive, and only errors that confirm the process is gone remove the lock.
The bug was reported in issue #18543 by GitHub user samline, who observed it on macOS with Bun and Astro 7.4.2. The reporter wrote that even astro dev status could remove the registration, and that a later start could create an untracked duplicate server. The PR, which closes that issue, was merged by matthewp on 2026-10-30.
Astro 7.4.5 shipped on 2026-11-02 at 14:21 UTC as a release, not a prerelease or draft, and it is the latest version on npm. The PR diff also changes stop: in the 7.4.5 source code, stopping a server the caller may not signal fails with “permission denied. Stop it from the environment that started it.” and leaves the lock file in place. The changelog entry does not mention that message.
Earlier lock file fixes covered Docker restarts and Linux thread IDs
Three older fixes touch the same lock file. In 7.2.2, released 2026-08-13 per npm, the changelog says astro dev no longer refused to start after a Docker restart when an unrelated process reused the lock file’s PID. 7.2.5, released 2026-08-24, fixed a second PID-reuse case in Docker.
In 7.4.2, released 2026-10-21 per npm, the changelog says Astro stopped treating a stale lock file holding a Linux thread ID as a running server. Before that fix, astro dev stop or astro dev --force could kill the unrelated process that owned the thread.
Limits
Nothing was run, so no astro dev status output is shown, and the docs and changelog read do not say what it prints for a server it may not signal. The non-empty-value reading of ASTRO_DEV_BACKGROUND and the “permission denied” message come from the 7.4.5 source, not the docs. The Windows Job Object reason rests on one code comment; the issue it links returned 404. Whether stop acts on a foreground server is not stated in the docs read. The EPERM case has one user report, and the PR describes the orphaned server, not the duplicate. On the am-i-vibing main branch, providers.ts lists Warp’s agent as an agent detected through OZ_RUN_ID; that change is unreleased, and npm still shows 0.5.0, published 2026-06-23, as latest.