# Idle sleep

> Put a running machine to sleep once it has done nothing for a while, how VMYard decides a machine is idle, and how idle sleep differs from auto-stop.

Idle sleep stops a running machine once it has shown no activity for a window you choose, from 5 minutes to 24 hours. It is **off by default** for every machine: you turn it on per machine when you create it or later.

The stop is an ordinary stop. The machine keeps its disk, and on hosts with snapshot sleep (KVM) also its memory and running processes, so `start` wakes it where it left off. Nothing is billed while it sleeps.

## Idle sleep and auto-stop

| | [Auto-stop](/docs/concepts/auto-stop) | Idle sleep |
| --- | --- | --- |
| Ends a run | a fixed time after the machine starts, whatever it does | once the machine has been idle for the whole window |
| Default | on, 1 hour | off |
| Range | 1 minute to 30 days | 5 minutes to 24 hours |
| Activity extends it | no | yes: any activity restarts the window |

Use both: auto-stop bounds a machine you forgot, and idle sleep ends a run as soon as the work is done. Whichever comes first stops the machine. The console's machine list shows the sooner one under **Stops / sleeps in**.

## How VMYard decides a machine is idle

The control plane checks running machines with idle sleep on about every 30 seconds. A machine is idle only while **every** signal stays quiet, without a break, for the whole window:

- No operation of the machine is pending, running, or uncertain, and none was requested or finished inside the window. Commands, background commands, file transfers, ports, SSH keys, lifecycle changes, environment installs, and snapshots all count.
- No [web terminal](/docs/guides/web-terminal) is open to it, and none closed inside the window.
- Its latest [metrics](/docs/guides/machine-metrics) are current and CPU, disk I/O, and network use are at or below small thresholds, with no minute inside the window above them. Port and SSH traffic shows up as network use.

The thresholds are set by the control plane, not by you, and may change.

**Missing data never counts as idle.** When metrics are missing, stale, or overdue, or the host can't measure a value, the window ends and starts again only once current, quiet metrics return. A machine whose host stopped reporting is never put to sleep because of it.

## Turn it on

In the console, choose **Sleep when idle** when you create a machine, or open the machine's overview and change **Idle sleep**. With the API, send `idle_sleep_after_seconds`:

```sh
# In the create body:
#   "idle_sleep_after_seconds": 900

curl -X PATCH "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idle_sleep_after_seconds": 900}'
```

`null` (or leaving the field out when you create) turns it off. Values outside 300 to 86,400 seconds answer `422` with a field error. Changing the setting restarts the idle window.

## What a machine reports

| Field | Meaning |
| --- | --- |
| `idle_sleep_after_seconds` | The window in seconds, or `null` when idle sleep is off. |
| `idle_since` | Start of the running machine's current unbroken idle window; `null` while it is active, its metrics are unknown, or idle sleep is off. |
| `idle_sleep_at` | When the machine sleeps if it stays idle (`idle_since` plus the window); `null` without an open window. The console counts down to it as **Sleeps in**. |
| `last_active_at` | The last activity VMYard observed; `null` until it saw any. The console shows it as **Last active**. |

## After it sleeps

An idle-sleep stop is a normal `stop` operation. `GET /v1/operations/{id}` and the `machine.stopped` [webhook](/docs/guides/webhooks) carry `stop_reason: "idle_sleep"`, and members who turned on the `idle_sleep` [email alert](/docs/guides/email-alerts) get an email naming the machine and the operation. In the console, open the machine's overview with `?operation=<id>` to see it as **Stopped: idle**.

Start the machine to wake it. A start, like any activity, begins a new idle window once the machine is quiet again.