> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic Sleep

> Idle VMs sleep automatically to release compute, preserve their state, and wake on the next connection.

Vers automatically puts idle VMs to sleep, releasing compute while preserving disk, memory, and running processes. The next connection wakes the VM from its saved state.

## How automatic sleep works

A VM becomes eligible for sleep when:

* it has no open connections through the Vers proxy, and
* its last proxied connection ended at least five minutes ago (or it has never received one and was created at least five minutes ago).

Vers checks periodically, so sleep may begin shortly after the inactivity window.

<Note>
  The inactivity window is deployment-specific. Five minutes is the default.
</Note>

Sleep is not deletion. The VM and its data remain available until you delete them.

## What counts as activity

Activity means a connection routed through the Vers proxy, such as:

* HTTP and HTTPS requests to the VM's Vers hostname or custom domain
* WebSocket connections
* SSH connections to the VM's public hostname
* raw TLS connections to a routed VM port

The inactivity window starts after the final connection closes.

<Warning>
  Outbound traffic does not count. Enable keep-alive for background jobs, builds, queue consumers, and polling services that have no inbound proxied connections.
</Warning>

## Wake on connection

New HTTP, WebSocket, SSH, and raw TLS connections wake a VM automatically. The first connection waits a few seconds while Vers restores the VM. If it is not ready within two minutes, the proxy returns an error.

<Note>
  Control-plane requests, such as status and SSH-key requests, do not wake a VM and can return `409 Conflict`. Connect directly to the VM to wake it.
</Note>

## Keep a VM running

Keep-alive is off by default. Enable it for outbound-only or background work, or when wake latency is unacceptable. Enabling it on a sleeping VM does not wake the VM; it prevents sleep after the next wake.

### Enable keep-alive when creating a VM

Set `keep_alive` when creating the VM:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS -X POST "https://api.vers.sh/api/v1/vm/new_root" \
  -H "Authorization: Bearer $VERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keep_alive": true,
    "vm_config": {
      "base_image_alias": "default"
    }
  }'
```

### Change keep-alive on an existing VM

Set `keep_alive` to `true` on an existing VM (or `false` to re-enable automatic sleep):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS -X PATCH "https://api.vers.sh/api/v1/vm/$VM_ID/keep-alive" \
  -H "Authorization: Bearer $VERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keep_alive": true }'
```

You can only change keep-alive for VMs owned by your organization.

### Check sleep and keep-alive state

`GET /api/v1/vms` returns each VM's `state` and `keep_alive` value:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS "https://api.vers.sh/api/v1/vms" \
  -H "Authorization: Bearer $VERS_API_KEY" \
  | jq '.[] | {vm_id, state, keep_alive}'
```

`state: "sleeping"` means the VM is preserved and ready to wake on its next connection.

## See also

* [Networking](/networking) — public hostnames, routed ports, and TLS
* [VM access](/vm-access) — SSH, command execution, and file transfer