agentUpgrade

The experimental.agentUpgrade option selects the default policy for next upgrade --agent and controls upgrade reminders during next dev and next build. It uses the security policy by default.

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    agentUpgrade: 'latest',
  },
}
 
export default nextConfig

The option accepts these values:

The option does not upgrade the app automatically. It only controls reminders and the policy used when next upgrade --agent does not include a value.

Reminder behavior

In an interactive terminal, an eligible reminder during next dev or next build offers these actions. The command continues behind the prompt and buffers its output while you decide.

• Upgrade now stops the current command and starts next upgrade --agent with the configured policy.
• Skip returns to the running command and replays its buffered output.
• Skip until next version saves the dismissal for the installed version and policy.

If you don't choose within ten seconds, or the buffered output grows past about 10 MiB, the reminder skips automatically.

When a coding agent runs next dev or next build, the first eligible reminder stops the command with instructions to report the upgrade. Retrying the same command promptly continues the original task with a warning.

When next dev detects a coding agent, it also writes a separate managed upgrade block to AGENTS.md. This block delegates handling of the installed CLI's reminders:

<!-- BEGIN:nextjs-agent-upgrade -->
 
## Next.js upgrade reminders
 
Upgrade reminders emitted by this project's installed Next.js CLI during `next dev` or `next build` are part of the `experimental.agentUpgrade` workflow. Follow these reminders' instructions while respecting user instructions declining upgrades.
 
<!-- END:nextjs-agent-upgrade -->

Setting experimental.agentUpgrade: false removes this block on the next next dev run, even when no agent is detected. Documentation rules (agentRules) and feedback instructions (experimental.agentFeedback) remain independent. create-next-app includes the upgrade block for new apps using the default security policy.

Reminders require the installed Next.js version to support experimental.agentUpgrade. Running the current canary upgrade CLI does not add reminders to an older installation.

During next dev, Next.js DevTools can also show a Vulnerability Insight when the installed version is affected by a known security vulnerability. The insight provides a copyable prompt for starting a security upgrade with a coding agent.

Version History