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

# Autosleep

> Automatically sleep idle Sailboxes and wake them on demand

Autosleep is optional and on by default. When it is on, Sail sleeps a Sailbox
that has sat idle and wakes it the moment anything needs it. This also lets a
Sailbox sleep while it is blocked waiting on an inference request, and wake
when the reply arrives. You are not
charged while a Sailbox sleeps, and waking takes a couple of seconds. Turn it
off for a Sailbox that must stay up, or change how long it must be idle first.

## What counts as idle

Sail sleeps a Sailbox on its own only when nothing inside would notice. All of
these must hold, and Sail checks them again just before the sleep:

* **No process has used CPU** since the last check. Even slow background work
  keeps the Sailbox awake.
* **No process is waiting on a timer.** The one exception is an alarm set for
  a wall-clock time, such as a job scheduled for 9:00. Sail lets the Sailbox
  sleep and wakes it shortly before the alarm is due, unless the alarm is only
  a couple of minutes away, in which case it stays up.
* **No TCP or UDP connection is open** from inside the Sailbox, in either
  direction, other than a request that is waiting on its reply.

A Sailbox has to stay in that state for the idle window before Sail sleeps
it. The default window is about five minutes; you can set your own, from one
second to an hour. Sail checks periodically, so the actual sleep can land a
little after the window ends.

## What survives

Sleeping checkpoints the whole machine. Disk, memory, and running processes
come back exactly as they were, and a process that was blocked, waiting for
input or a wall-clock alarm, carries on from where it was.

Any wake can come back cold instead, with the disk intact and nothing
running. Write code that expects a cold start.

## What wakes it

* A request to one of its exposed ports, HTTP or raw TCP. The connection is
  held while the Sailbox wakes, then forwarded.
* A command: `sail box exec`, `sail box shell`, a file transfer, or an SSH
  connection. Binding an existing Sailbox by id and running a command wakes
  it in every SDK, with no explicit resume.
* A wall-clock alarm a process inside set, as above.
* An explicit resume, or a scheduled wake.

## Turn it off, or change the window

`never` keeps the Sailbox running until you sleep, pause, or terminate it
yourself. A number of seconds from 1 through 3600 replaces the default idle
window. `auto` restores the default. The setting can be changed at any point
in a Sailbox's life, and your own `sleep`, `pause`, `resume`, and scheduled
wakes work the same whatever it is.

<div className="sail-prompt-cli">
  <CodeGroup>
    ```bash CLI theme={null}
    sail box create --app my-app --name session --auto-sleep never
    sail box auto-sleep <id> 30
    ```

    ```python Python theme={null}
    sb = sail.Sailbox.create(app=app, name="session", auto_sleep=sail.AutoSleep.never())
    sb.set_auto_sleep(sail.AutoSleep.not_before(30))
    ```

    ```typescript TypeScript theme={null}
    const sb = await Sailbox.create({
      app,
      name: "session",
      autoSleep: { automatic: false },
    });
    await sb.setAutoSleep({ automatic: true, minSecondsBeforeSleep: 30 });
    ```

    ```rust Rust theme={null}
    use sail::{AutoSleep, CreateSailboxRequest};
    use std::time::Duration;

    let sb = client
        .create_sailbox(
            &CreateSailboxRequest {
                app_id: app.id,
                name: "session".into(),
                auto_sleep: AutoSleep::Never,
                ..Default::default()
            },
            /* timeout */ None,
        )
        .await?;
    sb.set_auto_sleep(AutoSleep::NotBefore(Duration::from_secs(30))).await?;
    ```
  </CodeGroup>
</div>

The window only says when Sail may consider sleeping the Sailbox. It still
has to be idle by the rules above.

## Sleep it yourself

`sleep` checkpoints the Sailbox and powers it down right away; it wakes on the
same triggers as an automatic sleep. `pause` does the same but ignores traffic
and commands: only an explicit `resume` brings it back.

<div className="sail-prompt-cli">
  <CodeGroup>
    ```bash CLI theme={null}
    sail box sleep <id>
    sail box pause <id>
    sail box resume <id>
    ```

    ```python Python theme={null}
    sb.sleep()
    sb.pause()
    sb.resume()
    ```

    ```typescript TypeScript theme={null}
    await sb.sleep();
    await sb.pause();
    await sb.resume();
    ```

    ```rust Rust theme={null}
    sb.sleep(/* wake_at */ None).await?;
    sb.pause().await?;
    sb.resume().await?;
    ```
  </CodeGroup>
</div>

## Wake at a time

Give `sleep` a wake time and Sail restores the Sailbox when it arrives. Use it
for agents and services that sleep between runs and need to be up at a known
moment, such as a daily job or a follow-up an agent scheduled for itself.

<div className="sail-prompt-cli">
  <CodeGroup>
    ```bash CLI theme={null}
    sail box sleep <id> --wake-at 2h
    ```

    ```python Python theme={null}
    from datetime import datetime, timedelta, timezone

    sb.sleep(wake_at=datetime.now(timezone.utc) + timedelta(hours=2))
    ```

    ```typescript TypeScript theme={null}
    await sb.sleep(new Date(Date.now() + 2 * 60 * 60 * 1000));
    ```

    ```rust Rust theme={null}
    use sail::time::{Duration, OffsetDateTime};

    sb.sleep(Some(OffsetDateTime::now_utc() + Duration::hours(2))).await?;
    ```
  </CodeGroup>
</div>

A Sailbox holds one scheduled wake. An earlier request replaces it; a later
one leaves the sooner wake in place, and the call returns whichever won.
Calling `sleep` with a time on a Sailbox that is already asleep just updates
the wake. The CLI takes a delay like `30m` or `2h`, or an RFC 3339 timestamp.
The wake can land a little late, so give it a minute or two of headroom.
A paused Sailbox rejects a scheduled wake; only `resume` brings it back.