---
title: "Sleep: a service that sleeps costs nothing, the while.sh docs"
url: https://while.sh/en/docs/building-blocks/sleep/
updated: 2026-11-09
---

# Sleep

A rarely called service goes to sleep and reserves nothing. The first request wakes it up in a few seconds.

> You, to your agent: Let the demo service sleep when nobody is using it.

## What your agent writes

Your agent writes it in while.yaml, at the root of your app:

```yaml titre="while.yaml"
services:
  - name: web
    port: 3000
    sleep: 1h
environments:
  production:
    services:
      - name: web
        sleep: never
```

## When to use it

For a rarely called service: it reserves nothing while sleeping, and wakes up in 2 to 4 seconds, plus the app's startup.

## How it works

A web service or a site that no longer receives requests goes to sleep and no longer reserves anything. The first request wakes it and waits for it to answer.

## What to know

The setting goes per service in while.yaml. `sleep: 30m` puts it to sleep after 30 minutes without a request, and `sleep: never` keeps it always awake, with at least one instance; the delay is written in minutes or hours (30m, 2h). By default, a service stays awake in production, and goes to sleep after 30 minutes without a request elsewhere, as in a preview. A worker and a task never sleep.

A sleeping service restarts from one instance when it wakes: `scale.min` only counts if it does not sleep, and `scale.min: 0`, the old way of saying it, means `sleep: 30m`. while's background monitoring does not wake a sleeping service, but the `get_app_status` tool wakes it, except with `probe: false`. status also gives the wake-ups of the last 7 days (`wakeups.median_ms`): a heavy startup gains by loading what it can on demand.

A preview whose services all sleep, with no visit, read or deployment for 24 hours, has its database put to sleep. The next visit gets a "waking up" page (503) that reloads itself, and the database is ready in about ten seconds. A script gets 503 and Retry-After, and a deployment wakes the database and waits for it. A production database never sleeps.