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.
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.
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.
Wake at a time
Givesleep 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.
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.