Stop sandbox runtime with a reviewable cleanup result

Make cleanup part of the deliverable

A compute task is not complete merely because an output file exists. It also needs a known resource state and a usable artifact outside the execution environment. Decide what to retain, which services to stop and how to verify closure before creating the sandbox. Lupin exposes stop and resume, while deletion and dedicated port revocation are absent from the current public container API. Use those exact lifecycle terms in your product and task record. Calling a stopped resource deleted can mislead the user about both retained files and the possibility of later resumption.

Export verified work first

Download the required small artifact or use another approved storage path before stopping. The built-in file transport is base64 with a roughly two-megabyte bound, so larger results need a planned route. Verify file size, format and relevant contents before treating the exported copy as the deliverable. Keep a concise diagnostic record for failed stages without retaining unnecessary input data or secrets. A file still present inside a sandbox is not the same as a user-accessible completed result. Do not depend on a future resume as the only way to retrieve work the user needs now.

Stop workload processes deliberately

For an application server or multiprocess job, use the program's supported shutdown path when it needs to flush data or finish a transaction. The provider's broader stop behavior should not be treated as your application-level commit protocol. An abruptly stopped process may not have written its latest in-memory state to the artifact. Check final files and external effects before the lifecycle call. If a public port was published, stop the service according to the task's access plan and remember that the API does not provide a standalone revoke operation. Avoid promising immediate permanent URL removal without verifying the actual behavior.

await lupin.containers.stop(containerId, "task-cleanup-stop-001");
const containers = await lupin.containers.list();
// Inspect the known resource and retain unresolved cleanup errors.

Preserve the stop operation identity

Stop requires container_update permission and a stable Idempotency-Key. Keep that key and container_id with the cleanup stage. The route verifies provider closure before settling runtime and clears the running interval in its durable state. If a request fails or the response is lost, reconcile the original operation and resource instead of assuming shutdown happened. A failed status lookup may appear as unknown in a list response; that is not evidence of a stopped machine. Likewise, closing a desktop-shell window only disconnects the viewer and does not itself complete the stop operation.

Report unresolved closure separately

Save the work result and cleanup result as different fields. A transformation can succeed while its stop request remains uncertain, and a failed transformation can still leave a cleanly stopped resource. An actionable follow-up contains the container identifier, attempted stop time and sanitized error, not credentials or full logs. Once provider closure is confirmed, report the verified artifact and stopped state. If later work resumes the resource, give it a new authorized runtime stage and recheck application readiness. Reliable cleanup ends today's runtime clearly without inventing retention, deletion or process-continuation guarantees that the API does not make.

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 · long-running-tasks · command-history ↗Checked 2026-11-05

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