Understand what stop and resume mean for a sandbox

Resume is a provider lifecycle operation

Lupin supports stopping and resuming the same hosted container resource. That is useful when approved work must pause between compute stages, but it should not be described as durable checkpointing of an arbitrary running process. The Boat provider documents disk snapshots and restoration behavior, with details that can depend on how and when the resource stopped. Lupin exposes a narrower API than the provider's full snapshot product. Build a task that can verify its own files and restart its application if necessary instead of assuming that memory, network connections and every child process continue unchanged.

Save application state before stopping

A program may keep recent changes in memory or buffer writes. Finish the current logical stage, flush or close its output through the program's supported mechanism and verify the resulting file before calling stop. For a database or service with external effects, establish its own consistency boundary rather than relying on machine shutdown to commit work. Export important artifacts independently. The current public Lupin API does not expose saved-snapshot creation, point-in-time restore or retention management, so provider documentation for those features must not be presented as a capability the agent can call through the container surface.

Use explicit lifecycle identities

Stop and resume are mutations with stable Idempotency-Key values. Keep the container_id, operation key and observed lifecycle state with the task. If stop has an uncertain result, reconcile it before treating a later resume as a clean new stage. The stop route verifies provider closure before completing its runtime settlement. Resume on a resource already marked running can return the running representation without allocating another running interval. Do not use repeated resume calls as a readiness poll or as a way to extend a finite runtime lease implicitly.

await lupin.containers.stop(containerId, "stage-one-stop-001");
// Later, after authorization and billing readiness:
await lupin.containers.resume(containerId, "stage-two-resume-001");

Recheck after resumption

When a stopped resource resumes, billing-enforced workspaces reserve a new finite runtime interval. The provider may restore disk state, but the application should inspect the expected paths, dependency versions and service readiness before continuing. A desktop-shell link is minted separately and requires a running container. Old client connections and prior process identifiers may no longer be meaningful. If the task's previous stage wrote a manifest, compare it to the current files and decide which next stage is safe. A resumable task has explicit evidence of completed work, not merely a remembered command that once started.

Keep retention and availability claims narrow

Do not promise indefinite storage, unlimited paused time or a permanently reachable public preview. Provider retention policies and workspace billing configuration can change, and the Lupin API does not expose every upstream control. For a deliverable the user must keep, save a verified copy to the intended artifact location before stopping. If the resumed state differs from expectation, report the observed discrepancy and recover from the saved task inputs where authorized. This approach makes stop and resume useful operational tools while keeping the workflow correct when process memory or an old connection cannot be recovered.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

• docs.boat.dev · snapshots · stop ↗Checked 2026-11-05
• docs.boat.dev · snapshots · resume-and-fork ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.