Skip to content

Maintenance mode

Use the Maintenance mode section of System → Config to set a window and message for a migration or cutover; the old Maintenance address redirects there. Enabling maintenance does not run database migrations for you.

TargetBehavior
New model, tool, MCP and realtime requests503 with maintenance and retry headers; rejected before authentication, without request logs, charges or RPM consumption
Health and read-only model, quota and catalog interfacesRemain available; /health returns 200 with maintenance state
Existing streamsContinue and settle normally
Admin writesOptional freeze, enabled by default, with necessary exceptions such as maintenance controls

Maintenance configuration

  1. Set the expected duration (a positive whole number of minutes) and localized messages, preview what clients will see, and decide whether to freeze Admin writes. The duration is only a hint; maintenance never ends automatically.
  2. Enable and verify the banner and new-request response. Per-process caches introduce a short propagation delay. While maintenance is active, the same section shows the expected recovery time and lets you extend or end it.
  3. Wait for in-flight work before applying the migration or cutover instructions.
  4. Disable maintenance on the environment actually receiving traffic, then make a real test call.

Configuration read failures allow traffic. Maintenance mode does not replace enforced database or network isolation. Database cutovers may copy maintenance state, so check it explicitly after switching.

See the maintenance reference for exceptions, permissions and runtime details.