# Maintenance Mode

> Temporarily replace your app's public responses with a Watasu maintenance page.

Maintenance mode shows a simple maintenance page on every public HTTP endpoint
of an app, including its managed URL and custom domains.

Open **App → Settings → Maintenance mode**, or use the CLI:

```bash
watasu maintenance on --app my-app
watasu maintenance status --app my-app
watasu maintenance off --app my-app
```

Changing maintenance requires **Manage** access. The CLI waits for the routing
change by default. Use `--no-wait` to return immediately, `--timeout 120` to set
the wait limit, or `--json` for structured output. App selection also supports
`--remote` and the current repository's Watasu remote.

The dashboard and API distinguish the requested setting from the last
successfully applied setting. If an update fails, retry it. If another routing
operation is running, wait for it to finish before changing maintenance.

## What visitors receive

The page returns **503 Service Unavailable**, `Retry-After: 60`, and
`Cache-Control: no-store`. Search engines are instructed not to index it.
Requests with `Accept: application/json` receive a JSON error with
`error: "maintenance"` and `status: 503`.

New HTTP requests and WebSocket connections receive this response. Existing
connections may continue until they close. Workers, scheduled jobs, private
network traffic, and deployments continue running. Maintenance does not scale
down the app or change its billing, and remains enabled across deployments.

Maintenance applies to the whole app. There are no path, IP, or user bypasses.
TLS certificates continue to be managed while maintenance is enabled.

## API and AI clients

* `GET /v1/apps/:app/maintenance` reads maintenance state.
* `PUT /v1/apps/:app/maintenance` with `{"enabled": true}` or `{"enabled": false}`
  changes it. A `202` response means routing is being updated; poll `GET` until
  `maintenance.status` is `ready`. `maintenance.applied` is the last successfully
  applied value. A `failed` status requires a retry.
* Reading requires `read_app_resources`; changing also requires
  `mutate_app_resources`.
* MCP provides `maintenance_status` and `maintenance_set` with the same access
  rules. Changes require the MCP `write` scope.

## Other platform pages

An address with no connected app returns **404 App not found**. If the edge
cannot reach an app, it returns a Watasu page with the corresponding **502**,
**503**, or **504** status. Error responses returned by your app retain your
app's content.

An unknown custom domain or a domain awaiting its certificate cannot display
an HTTPS page. Watasu rejects the TLS connection until it has a matching, valid
certificate. See [custom domains](https://docs.watasu.io/apps/custom-domains.md).

[View this page on the web](https://docs.watasu.io/apps/maintenance/)