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 a connection it opened to another service, stays awake. A server that is only listening for inbound requests, over TCP or UDP, does not keep it awake. Instead, a request to one of its exposed ports wakes the Sailbox, and the server receives it once the Sailbox is running. A UDP socket connected to a peer counts as an open connection for as long as it stays open; other UDP traffic counts until it has been quiet for up to two minutes. A connection to one of the Sailbox’s exposed ports does not keep it awake once the connection goes quiet. An SSH session orsail box shell left open
does not end when the Sailbox sleeps, and the next keystroke wakes it. A
connection through a
tunnel keeps
the Sailbox awake while it is open, including one that sail box shell
forwards to your machine.
Once a Sailbox is idle, Sail waits a minimum time before sleeping it. The wait
is 30 seconds by default (a new devbox starts at five
minutes), and you can change it per Sailbox. When a resume, traffic, or a
command stops a sleep that is in progress, the wait starts over from that
moment.
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, or new data on a connection that was open when it slept. Sail holds the request or data while the Sailbox wakes, then delivers it.
- A datagram to one of its exposed UDP ports. It is delivered once the Sailbox is running.
- 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.
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.
A resume that arrives while a sleep or pause of the same Sailbox is still
in progress keeps that Sailbox running. The sleep or pause call then fails
with a conflict error (HTTP 409), which the SDKs do not retry, and resume
returns once the Sailbox is running. Traffic and commands do the same for a
sleep, including an automatic sleep, but never for a pause. If the Sailbox
has already started powering down, it finishes going to sleep and wakes as
usual.
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 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.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.