Set command timeouts without assuming cancellation

A command has more than one deadline

A hosted command crosses your HTTP client, Lupin's API, the provider request and the process running inside the sandbox. Those layers can stop waiting at different times. Lupin's Boat adapter clamps a requested command timeout to a range of one through six hundred seconds, while its provider fetch also has a twenty-second request deadline. A caller therefore must not interpret a disconnected request as proof the process was killed at the same instant. Define the command's expected duration and observable result before running it, and make uncertainty an explicit possible outcome.

Keep the total resource budget separate

The sandbox's finite runtime lease controls how long the resource is authorized to run; timeout_seconds on a command controls that command request. A long command timeout cannot extend an expired resource lease. In billing-enforced workspaces, creation and resume reserve bounded runtime under the plan before touching the provider. Choose a command budget that leaves time to inspect results, export artifacts and stop the sandbox. Do not assume the provider's default lifetime or a successful shell connection grants unlimited runtime. Capability, billing and permission prerequisites remain relevant throughout the task.

Use small stages with explicit outputs

Split a large transformation into independently inspectable stages when the workload supports it: validate input, transform to a temporary artifact, then publish the finished artifact. This reduces the amount of ambiguous work after a timeout. It does not make every command safe to repeat. A stage that sends an external request or mutates a database still needs its own idempotent design. Keep the command string, expected output path and operation key together in the task record. For a pure local transform, a manifest or output checksum can help show whether a previous attempt already finished.

{"command":"pwd","timeout_seconds":30}

Reconcile before issuing another command

With durable storage enabled, preserve an Idempotency-Key on command requests. A repeated accepted or uncertain command can return reconciliation_required rather than execute again. Read command history and inspect relevant process or file state through an authorized observation before creating a new attempt. The current history response gives command metadata and status, not a guaranteed replay of the original stdout and stderr. A missing client result should remain missing until evidence resolves it. Do not manufacture success from a plausible artifact name or start the same side effect under a new key merely to obtain a clean response.

Report the limit that actually stopped progress

When a task cannot finish, state whether the client lost contact, the provider request failed, the command exited nonzero or the resource runtime ended. Save any verified partial artifact and identify the next safe diagnostic step. A timeout alone does not prove failure inside the guest, and a zero process exit does not establish semantic correctness of the output. Stop or reconcile idle resources separately from command recovery. This disciplined distinction lets an operator decide whether to extend a later authorized run, reduce the workload or investigate provider behavior without guessing which layer expired.

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.python.org · 3 · library · subprocess.html ↗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.