Manage multiprocess work inside a task sandbox

Know what the public command API provides

Lupin's run endpoint executes a synchronous command through the hosted provider and returns its process result when available. It does not expose a general durable job orchestration API with task dependencies, worker queues or process cancellation handles. A command can still start a server or child process inside the guest, but your workload then owns that process's supervision. Define which processes should exist, how their readiness is checked and how they stop. Starting a process in the background is a shell technique, not proof that the application now has a managed service lifecycle.

Use a small process map

For a preview workload, write down the application server, any build watcher and the health endpoint each needs. Keep them in a task-owned directory with separate bounded logs. Record process identifiers only as observations within the current environment; a provider resume can make old identifiers meaningless. Avoid launching duplicate servers merely because a previous command response was lost. Inspect the current process and port state first. A single well-understood server is easier to clean up than several speculative copies competing for the same port and producing interleaved output.

Separate launch from readiness

A shell returning after backgrounding a process proves little about whether the service is usable. Dependencies, migrations or application initialization may still be incomplete. Check a task-specific readiness signal from within the sandbox before publishing the port. Then verify the public endpoint's authentication and content after publication. Lupin's publish-port route invokes the provider's host command; it does not launch or health-check the server for you. The finite resource lease continues while these stages run, so reserve time for readiness observations and failure cleanup rather than spending the entire budget starting processes.

{"command":"ps -eo pid,ppid,comm | head -n 20","timeout_seconds":30}

Handle child lifetimes intentionally

A timeout or disconnected parent request does not universally establish that every child stopped. Use the runtime's supported process-group or supervision mechanisms when appropriate and implement an explicit graceful shutdown for programs that must flush data. Keep stdout and stderr bounded so a noisy child cannot overwhelm the agent's useful observations. For external side effects, use application-level idempotency and reconciliation rather than assuming a restart is harmless. A background worker that sends requests after the main task finished can exceed the user's intended scope even while the machine itself remains isolated.

Finish the whole process tree

At completion, verify the artifact or preview result, stop unneeded application processes and then stop the sandbox. The current API exposes stop and resume, not a standalone process-control or port-revocation catalog. Keep the work result and resource cleanup result separate when errors occur. If a resumed resource needs the application again, recheck files and readiness and start the required process deliberately. Do not claim that every in-memory job continues across stop and resume. A multiprocess task is manageable when its process map, observations and shutdown path are explicit enough for another operator to understand.

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 · long-running-tasks · background-commands ↗Checked 2026-11-05
• docs.python.org · 3 · library · subprocess.html ↗Checked 2026-11-05

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