> ## 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.
# Lifecycle
> Checkpoint, start from checkpoint, pause, sleep, resume, schedule wakes, upgrade, and terminate Sailboxes
Sailboxes preserve their writable disk, in-memory state, and in-flight network
requests across checkpoints and resumes.
Any Sailbox you resume can come back cold instead, with the disk intact and
nothing running, and one that has an upgrade waiting always does. Write code
that expects a cold start.
The examples below assume a running Sailbox `sb`.
```python Python theme={null}
checkpoint = sb.checkpoint() # Create a durable checkpoint handle
child = sail.Sailbox.from_checkpoint(checkpoint.checkpoint_id, name="rollout-1")
sb.pause() # Checkpoint and pause until explicit resume
sb.sleep() # Checkpoint and sleep until network ingress, exec, or resume
sb.resume() # Resume a paused or sleeping Sailbox
sb.upgrade() # Update the Sailbox runtime by rebooting on the same disk
sb.terminate() # Permanently destroy the Sailbox
```
```typescript TypeScript theme={null}
const checkpoint = await sb.checkpoint(); // Create a durable checkpoint handle
const child = await Sailbox.fromCheckpoint({
checkpointId: checkpoint.checkpointId,
name: "rollout-1",
});
await sb.pause(); // Checkpoint and pause until explicit resume
await sb.sleep(); // Checkpoint and sleep until network ingress, exec, or resume
await sb.resume(); // Resume a paused or sleeping Sailbox
await sb.upgrade(); // Update the Sailbox runtime by rebooting on the same disk
await sb.terminate(); // Permanently destroy the Sailbox
```
```rust Rust theme={null}
use sail::CheckpointOptions;
// Create a durable checkpoint handle
let checkpoint = sb.checkpoint(CheckpointOptions::default()).await?;
let child = client
.create_from_checkpoint(&checkpoint.checkpoint_id, "rollout-1", /* timeout */ None)
.await?;
sb.pause().await?; // Checkpoint and pause until explicit resume
sb.sleep(/* wake_at */ None).await?; // Checkpoint and sleep until ingress, exec, or resume
sb.resume().await?; // Resume a paused or sleeping Sailbox
sb.upgrade().await?; // Update the Sailbox runtime
sb.terminate().await?; // Permanently destroy the Sailbox
```
Sail may also sleep a Sailbox on its own, but only when nothing would notice:
no CPU or network activity, no process waiting on a timer, and no open
connections a sleep would break. A slept Sailbox wakes transparently on
traffic or the next operation.
Waking takes a couple of seconds. That is free for a batch job and unwelcome if
someone is waiting at a terminal, so you can turn automatic sleep off for a
Sailbox, or choose how long it must be idle before Sail may sleep it.
```python Python theme={null}
sb = sail.Sailbox.create(
app=app,
name="interactive-session",
auto_sleep=sail.AutoSleep.never(),
)
# Or use a 30-second idle window instead of Sail's default.
sb.set_auto_sleep(sail.AutoSleep.not_before(30))
```
```typescript TypeScript theme={null}
const sb = await Sailbox.create({
app,
name: "interactive-session",
autoSleep: { automatic: false },
});
// Or use a 30-second idle window instead of Sail's default.
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: "interactive-session".into(),
auto_sleep: AutoSleep::Never,
..Default::default()
},
/* timeout */ None,
)
.await?;
// Or use a 30-second idle window instead of Sail's default.
sb.set_auto_sleep(AutoSleep::NotBefore(Duration::from_secs(30))).await?;
```
A numeric setting replaces Sail's default idle wait, so it can make automatic
sleep happen sooner or later. The idle window only controls when Sail may
consider sleeping the Sailbox. Sail still waits until the Sailbox is fully idle,
and its periodic check can make the actual sleep happen later. Choose a whole
number of seconds from 1 through 3600. A value of 0 restores Sail's default.
Other numeric values are rejected. Your own `sleep()`, `pause()`, `resume()`,
and scheduled wakes work the same either way.
## Checkpoint
`checkpoint()` creates a durable checkpoint handle. Running Sailboxes are
snapshotted first. Paused and sleeping Sailboxes return a handle to their
existing checkpoint without waking.
```python Python theme={null}
sb.exec("python3 setup.py").wait()
checkpoint = sb.checkpoint(name="after-setup", ttl_seconds=30 * 86400)
print(checkpoint.expires_at)
```
```typescript TypeScript theme={null}
await (await sb.exec("python3 setup.py")).wait();
const checkpoint = await sb.checkpoint({
name: "after-setup",
ttlSeconds: 30 * 86400,
});
console.log(checkpoint.expiresAt);
```
```rust Rust theme={null}
use sail::CheckpointOptions;
use std::time::Duration;
use sail::ExecOptions;
let setup = sb
.exec(
vec!["python3".to_string(), "setup.py".to_string()],
ExecOptions::default(),
)
.await?;
setup.wait().await?;
let checkpoint = sb
.checkpoint(CheckpointOptions {
name: Some("after-setup".to_string()),
ttl: Some(Duration::from_secs(30 * 86400)),
})
.await?;
println!("{:?}", checkpoint.expires_at);
```
Call `checkpoint()` after important setup, such as installing packages,
fetching remote data, or writing files. On host failure, Sail restores from the
most recent completed checkpoint and does not replay commands that ran before
that checkpoint.
`name` labels the handle. A checkpoint lasts seven days unless you set a TTL.
Set one when you keep a checkpoint to reuse as a template, so the handle does
not expire while you still need it. The returned handle carries the expiry time
(`expires_at`), after which starting a Sailbox from it fails.
## Start From Checkpoint
Create a separate running Sailbox from a durable checkpoint handle:
```python Python theme={null}
checkpoint = sb.checkpoint()
child = sail.Sailbox.from_checkpoint(
checkpoint.checkpoint_id,
name="experiment-1",
)
```
```typescript TypeScript theme={null}
const checkpoint = await sb.checkpoint();
const child = await Sailbox.fromCheckpoint({
checkpointId: checkpoint.checkpointId,
name: "experiment-1",
});
```
```rust Rust theme={null}
use sail::CheckpointOptions;
let checkpoint = sb.checkpoint(CheckpointOptions::default()).await?;
let child = client
.create_from_checkpoint(&checkpoint.checkpoint_id, "experiment-1", /* timeout */ None)
.await?;
```
The child restores the memory saved in the checkpoint as well as the writable
disk, so processes the original was running carry on in the child. Commands you
started with `exec` stop in the child, though their writes up to the checkpoint
are kept, and one you started with the background option keeps running there.
Start the other commands the child needs again.
Sometimes the child comes up cold instead, with the disk intact and nothing
running. Write code that expects a cold start.
The child gets new Sail identity and networking. Active TCP connections are
reset in the child. A child starts with no inherited ingress, so add the ports
the child should publish with
[`expose`](/sailboxes-networking#add-or-remove-ports-at-runtime).
`checkpoint()` does not support a Sailbox that has volume mounts. Create a
separate Sailbox without volume mounts before you create a checkpoint handle.
Upgrade a Sailbox that uses an older guest payload before checkpointing it.
Sleeping and paused Sailboxes can be cloned too: `checkpoint()` returns the
existing checkpoint handle without waking the parent. Starting multiple
children from the same checkpoint reuses the same checkpoint artifacts, so the
second and later children avoid re-checkpointing the parent.
### Fan Out to Many Sailboxes
Starting many children from one checkpoint is the fast path to a fleet of
identical environments, for example agent rollouts, parallel test shards, or
grading many submissions at once. Prepare one Sailbox (install dependencies,
warm caches, start servers), checkpoint it, then start every worker from that
checkpoint instead of repeating the setup in each one:
```python Python theme={null}
import asyncio
checkpoint = sb.checkpoint()
async def fan_out(n: int) -> list[sail.Sailbox]:
results = await asyncio.gather(
*(
sail.Sailbox.from_checkpoint.aio(
checkpoint.checkpoint_id,
name=f"worker-{i}",
timeout=600,
)
for i in range(n)
),
# Keep the children that came up even if some restores fail.
return_exceptions=True,
)
return [r for r in results if isinstance(r, sail.Sailbox)]
children = asyncio.run(fan_out(32))
```
```typescript TypeScript theme={null}
const checkpoint = await sb.checkpoint();
const results = await Promise.allSettled(
Array.from({ length: 32 }, (_, i) =>
Sailbox.fromCheckpoint({
checkpointId: checkpoint.checkpointId,
name: `worker-${i}`,
timeoutSeconds: 600,
}),
),
);
// Keep the children that came up even if some restores fail.
const children = results.flatMap((r) =>
r.status === "fulfilled" ? [r.value] : [],
);
```
```rust Rust theme={null}
use std::time::Duration;
use sail::CheckpointOptions;
let checkpoint = sb.checkpoint(CheckpointOptions::default()).await?;
// Build the names first so each one outlives the call that borrows it.
let names: Vec = (0..32).map(|i| format!("worker-{i}")).collect();
let results = futures::future::join_all(names.iter().map(|name| {
client.create_from_checkpoint(
&checkpoint.checkpoint_id,
Some(name.as_str()),
Some(Duration::from_secs(600)),
)
}))
.await;
// Keep the children that came up even if some restores fail.
let children: Vec = results.into_iter().flatten().collect();
```
Use the concurrent forms shown here (`.aio` twins in Python, promises in
TypeScript, joined futures in Rust) so the restores overlap instead of running
one at a time, and collect the results per child, as the examples do, so one
failed restore does not cost you the children that did come up. Give each
child a distinct `name`, and pass a `timeout` so a stuck restore fails that
child instead of stalling the whole batch.
Each child is a full, separate Sailbox: it bills like one and keeps running
until it sleeps or you terminate it, so clean up the fleet when the work is
done. If one process drives hundreds of Sailboxes concurrently, you can also
give the SDK's thread pool more headroom; see
[Configuration](/reference/sdk-configuration#worker-threads).
## Pause
`pause()` checkpoints the Sailbox and powers it down until you explicitly resume
it:
```python Python theme={null}
sb.pause()
sb.resume()
```
```typescript TypeScript theme={null}
await sb.pause();
await sb.resume();
```
```rust Rust theme={null}
sb.pause().await?;
sb.resume().await?;
```
Use pause when you want to preserve state but do not want the Sailbox to wake on
network traffic.
## Sleep
`sleep()` checkpoints the Sailbox and powers it down until network ingress,
exec, or an explicit resume wakes it:
```python Python theme={null}
sb.sleep()
```
```typescript TypeScript theme={null}
await sb.sleep();
```
```rust Rust theme={null}
sb.sleep(/* wake_at */ None).await?;
```
Use sleep for idle services that should wake when they receive traffic.
## Resume
`resume()` restores a paused or sleeping Sailbox:
```python Python theme={null}
sb.resume()
```
```typescript TypeScript theme={null}
await sb.resume();
```
```rust Rust theme={null}
sb.resume().await?;
```
`exec` and file operations wake a sleeping Sailbox automatically, so binding
an existing Sailbox by id needs no explicit resume in any language.
## Sleep Until a Wake
Pass a wake time to `sleep()` to schedule a wall-clock wake as the Sailbox
goes down. When the moment arrives and the Sailbox is still sleeping, Sail
restores it:
```python Python theme={null}
from datetime import datetime, timedelta, timezone
effective = sb.sleep(wake_at=datetime.now(timezone.utc) + timedelta(hours=2))
```
```typescript TypeScript theme={null}
const effective = await sb.sleep(new Date(Date.now() + 2 * 60 * 60 * 1000));
```
```rust Rust theme={null}
use sail::time::{Duration, OffsetDateTime};
let effective = sb
.sleep(Some(OffsetDateTime::now_utc() + Duration::hours(2)))
.await?;
```
```bash CLI theme={null}
sail box sleep --wake-at 2h
```
Each Sailbox holds one scheduled wake. A request earlier than the current
scheduled wake replaces it. A later request leaves the sooner wake in place.
The call returns the effective wake time (the sooner of the two). Schedule
the next wake after the current one fires if you need a series.
Calling `sleep` with a wake time on a Sailbox that is already sleeping just
updates the scheduled wake. The CLI accepts a delay like `30m` or `2h`, or
an absolute RFC 3339 timestamp. The wake can fire a little after the time
you set, so treat it as approximate. Schedule a minute or two of headroom
rather than an exact deadline. Paused Sailboxes only wake on an explicit
resume and reject scheduled wakes.
Use scheduled wakes for agents and services that sleep between runs and need
to be running again at a known time, such as a daily job or a follow-up an
agent set for itself.
## Upgrade
`upgrade()` reboots the Sailbox on its same disk onto the latest in-guest Sail
agent, picking up new features, fixes, and performance improvements without
recreating the Sailbox:
```python Python theme={null}
result = sb.upgrade()
print(result.applied)
```
```typescript TypeScript theme={null}
const { applied } = await sb.upgrade();
```
```rust Rust theme={null}
let outcome = sb.upgrade().await?;
println!("applied now: {}", outcome.applied);
```
```bash theme={null}
sail box upgrade
```
The filesystem is fully preserved; running processes stop and the Sailbox boots
fresh, like a machine reboot. Restart any long-running services afterwards.
On a running Sailbox the upgrade applies immediately and `applied` is true. On
a paused or sleeping Sailbox the upgrade is recorded without waking it and
`applied` is false; it applies automatically the next time the Sailbox wakes. A
Sailbox that is already on the current runtime version reports true without
rebooting.
A Sailbox whose runtime is too old for Sail to resume safely is
upgraded automatically the next time it wakes, as if `upgrade()` had been
called on it first.
Before a runtime version reaches that automatic-upgrade cutoff, `get` and
`list` return a `deprecation` notice with a deadline and upgrade instructions.
The CLI and Python/TypeScript SDKs also surface the first such notice as a
warning once per process (Python emits `SailDeprecationWarning` through the
`warnings` module); Rust callers
can install a callback with `sail::set_notice_handler`. Treat it as advance
notice to schedule `upgrade()` on your own terms before the deadline; it is not
an immediate failure.
## Terminate
`terminate()` permanently destroys the Sailbox:
```python Python theme={null}
sb.terminate()
```
```typescript TypeScript theme={null}
await sb.terminate();
```
```rust Rust theme={null}
sb.terminate().await?;
```
Termination is not reversible. Use `pause()` or `sleep()` when you want to keep
the VM state for later.