Lifecycle

Sailboxes preserve their writable disk, in-memory state, and in-flight network requests across checkpoints and resumes. The examples below assume a running Sailbox sb.

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

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

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", /* max_lifetime */ 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 also sleeps a Sailbox on its own once it has been truly idle for a while, and wakes it on traffic or the next operation. Waking takes a few seconds, so you can turn automatic sleep off for a Sailbox, or choose how long it must be idle before Sail sleeps it.

sb = sail.Sailbox.create(
    app=app,
    name="interactive-session",
    auto_sleep=sail.AutoSleep.never(),
)

# Or sleep only after 10 minutes idle.
sb.set_auto_sleep(sail.AutoSleep.not_before(600))

const sb = await Sailbox.create({
  app,
  name: "interactive-session",
  autoSleep: { automatic: false },
});

// Or sleep only after 10 minutes idle.
await sb.setAutoSleep({ automatic: true, minSecondsBeforeSleep: 600 });

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()
        },
    )
    .await?;

// Or sleep only after 10 minutes idle.
sb.set_auto_sleep(AutoSleep::NotBefore(Duration::from_secs(600))).await?;

The minimum idle time is a whole number of seconds from 1 through 3600; 0 restores Sail’s default of 30 seconds. See Autosleep.

Limit a Sailbox’s lifetime

Set max_lifetime_seconds when creating a Sailbox to have Sail permanently terminate it after a fixed wall-clock lifetime. The limit starts at the Sailbox’s created_at, after image preparation, and includes waiting for capacity, sleeping, and paused time. Activity and resuming do not reset it. Sail enforces the limit even if your client disconnects or crashes.

sb = sail.Sailbox.create(app=app, name="rollout", max_lifetime_seconds=3600)
print(sail.Sailbox.get(sb.sailbox_id).expires_at)

const sb = await Sailbox.create({ app, name: "rollout", maxLifetimeSeconds: 3600 });
console.log((await Sailbox.get(sb.sailboxId)).expiresAt);

let sb = client.create_sailbox(
    &CreateSailboxRequest {
        app_id: app.id.clone(),
        name: "rollout".into(),
        max_lifetime: Some(std::time::Duration::from_secs(3600)),
        ..Default::default()
    },
).await?;

sail box create --app rollouts --name rollout --max-lifetime-seconds 3600

Use whole seconds from 1 through 4294967295, or omit the limit for unlimited lifetime. The limit is fixed at creation. Get/list return expires_at (expiresAt in TypeScript), or null for unlimited lifetime. Sail checks expiration about every ten seconds and uses the same cleanup as terminate(). from_checkpoint (fromCheckpoint in TypeScript, box from-checkpoint in the CLI) accepts a separate limit for the new Sailbox; it does not inherit the source’s limit. Checkpoint ttl_seconds controls how long the saved checkpoint remains usable.

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.

sb.exec("python3 setup.py").wait()
checkpoint = sb.checkpoint(name="after-setup", ttl_seconds=30 * 86400)
print(checkpoint.expires_at)

await (await sb.exec("python3 setup.py")).wait();
const checkpoint = await sb.checkpoint({
  name: "after-setup",
  ttlSeconds: 30 * 86400,
});
console.log(checkpoint.expiresAt);

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 includes 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:

checkpoint = sb.checkpoint()
child = sail.Sailbox.from_checkpoint(
    checkpoint.checkpoint_id,
    name="experiment-1",
)

const checkpoint = await sb.checkpoint();
const child = await Sailbox.fromCheckpoint({
  checkpointId: checkpoint.checkpointId,
  name: "experiment-1",
});

use sail::CheckpointOptions;

let checkpoint = sb.checkpoint(CheckpointOptions::default()).await?;
let child = client
    .create_from_checkpoint(&checkpoint.checkpoint_id, "experiment-1", /* max_lifetime */ None)
    .await?;

The child restores the memory saved in the checkpoint as well as the writable disk, so processes the original was running continue 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. The child gets new Sail identity and networking. Active TCP connections are reset in the child. A child does not inherit ingress, so add the ports the child should publish with expose.

Checkpoints with volumes

Checkpoints save the Sailbox’s writable disk and memory, not a version of its shared volumes. Children reattach the same volumes at the saved paths and keep each mount’s read-only setting.

Volume changes remain shared between the source and its children. Restoring an older checkpoint does not roll back those changes.
Mounts added to the source after a checkpoint are not attached to that checkpoint’s children.
Copied volume clients are discarded without flushing. Applications must reopen volume files in a child; inherited open file handles are not usable.
Existing private bind mounts still refer to the old mount. Recreate them in the child before using the volume through those paths or containers.
A deleted or unavailable volume prevents creation of the child.
Upgrade older Sailboxes before checkpointing with volumes. Legacy NFS volumes are not supported by this memory-preserving checkpoint path.

Save pending volume writes before checkpointing if the children need them. A checkpoint is not a backup of volume contents.

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:

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}",
            )
            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))

const checkpoint = await sb.checkpoint();

const results = await Promise.allSettled(
  Array.from({ length: 32 }, (_, i) =>
    Sailbox.fromCheckpoint({
      checkpointId: checkpoint.checkpointId,
      name: `worker-${i}`,
    }),
  ),
);

// Keep the children that came up even if some restores fail.
const children = results.flatMap((r) =>
  r.status === "fulfilled" ? [r.value] : [],
);

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<String> = (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,
        name.as_str(),
        /* max_lifetime */ None,
    )
}))
.await;

// Keep the children that came up even if some restores fail.
let children: Vec<sail::Sailbox> = 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. 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.

Pause

pause() checkpoints the Sailbox and powers it down until you explicitly resume it:

sb.pause()
sb.resume()

await sb.pause();
await sb.resume();

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:

sb.sleep()

await sb.sleep();

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:

sb.resume()

await sb.resume();

sb.resume().await?;

exec and file operations wake a sleeping Sailbox automatically, so binding an existing Sailbox by id does not need an 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:

from datetime import datetime, timedelta, timezone

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

const effective = await sb.sleep(new Date(Date.now() + 2 * 60 * 60 * 1000));

use sail::time::{Duration, OffsetDateTime};

let effective = sb
    .sleep(Some(OffsetDateTime::now_utc() + Duration::hours(2)))
    .await?;

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

Each Sailbox can have one scheduled wake at a time. 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 happens 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 happen 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:

result = sb.upgrade()
print(result.applied)

const { applied } = await sb.upgrade();

let outcome = sb.upgrade().await?;
println!("applied now: {}", outcome.applied);

sail box upgrade <id>

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. The upgrade 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 report 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:

sb.terminate()

await sb.terminate();

sb.terminate().await?;

Termination is not reversible. Use pause() or sleep() when you want to keep the VM state for later.

Getting started

Inference

Sailboxes

Guides

Security & compliance

Limit a Sailbox’s lifetime

Checkpoint

Start From Checkpoint

Checkpoints with volumes

Fan Out to Many Sailboxes

Pause

Sleep

Resume

Sleep Until a Wake

Upgrade

Terminate

​Limit a Sailbox’s lifetime

​Checkpoint

​Start From Checkpoint

​Checkpoints with volumes

​Fan Out to Many Sailboxes

​Pause

​Sleep

​Resume

​Sleep Until a Wake

​Upgrade

​Terminate

Limit a Sailbox’s lifetime

Checkpoint

Start From Checkpoint

Checkpoints with volumes

Fan Out to Many Sailboxes

Pause

Sleep

Resume

Sleep Until a Wake

Upgrade

Terminate