Autosleep

Automatically sleep idle Sailboxes and wake them on demand

Autosleep is on by default. Sail watches each Sailbox and, once it has been truly idle for a while, puts it to sleep. The next request or command wakes it. You are not charged while a Sailbox sleeps.

Waking takes a few seconds, so the first request or command after a sleep is slower than usual.

When a Sailbox sleeps

Sail uses heuristics to tell when a Sailbox is truly idle, meaning nothing running inside it would notice a sleep. A Sailbox doing work, or holding open connections, stays awake.

Once a Sailbox is idle, Sail waits a minimum time before sleeping it. The wait is 30 seconds by default, and you can change it per Sailbox.

What survives

Sleeping checkpoints the whole machine. Disk, memory, and running processes come back exactly as they were.

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. Running a command on a sleeping Sailbox wakes it in every SDK.
• A wall-clock alarm a process inside set, such as a job scheduled for 9:00.
• An explicit resume, a scheduled wake, or a cron job that is due.

Configure it

Set the minimum idle time to a number of seconds from 1 through 3600. never keeps the Sailbox running until you sleep, pause, or terminate it yourself. auto restores the default. You can change the setting at any time, and it has no effect on your own sleep, pause, resume, and scheduled wakes.

CLI

sail box create --app my-app --name session --auto-sleep never
sail box auto-sleep <id> 600

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.

CLI

sail box sleep <id>
sail box pause <id>
sail box resume <id>

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.

CLI

sail box sleep <id> --wake-at 2h

A Sailbox has one scheduled wake at a time. A request for an earlier time replaces it, and a request for a later time leaves the sooner wake in place. The call returns the wake that remains scheduled. 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 be a little late, so give it a minute or two of headroom. A paused Sailbox rejects a scheduled wake. Only resume brings it back.

Run a command on a schedule

A cron job runs a shell command in a Sailbox on a schedule. If the Sailbox is asleep when a run is due, Sail wakes it and starts the command. Autosleep then puts the Sailbox back to sleep once it is idle.

CLI

sail box cron add <id> "0 9 * * 1-5" "python /app/report.py" --timezone America/New_York
sail box cron list <id>
sail box cron remove <id> <cron-job-id>

The schedule is a cron expression with five fields: minute, hour, day of month, month, and day of week. The one above runs at 9:00 on weekdays. Times are UTC unless you name a time zone.

The command runs the way an exec command does. See the cron namespace for its options.

• A run can start a little late, more so when the Sailbox has to wake first.
• Output is not kept. Have the command write what you need to a file, for example python /app/report.py >> /var/log/report.log 2>&1.
• A run that cannot start is skipped, and is not made up later. That happens when the Sailbox is paused or fails to wake.
• Runs do not wait for each other. A run still going when the next is due does not delay it.
• Jobs belong to one Sailbox, which holds up to 50. They are removed when it is terminated, and a fork or a Sailbox created from a checkpoint starts with none.