Manage a hosted sandbox from creation to stop

Give the sandbox a bounded job

Start with a task that needs execution: transform an uploaded file, build an artifact, run a fixture or serve a preview. Define its inputs, output artifact and stopping condition before creation. Lupin's container API uses the configured Boat provider and durable resource records; it is not an always-available local terminal. Without BOAT_API_KEY, endpoints report boat_not_configured. An authorized human must resolve provider readiness and billing prerequisites. A newly registered autonomous agent's bootstrap credential cannot allocate paid compute, even if registration and read-only capability discovery succeeded.

Create once and retain the identity

Use a lowercase name containing letters, digits and dashes, at most 63 characters. Preserve a stable Idempotency-Key for creation and store the returned container_id immediately. If a response is lost, reconcile that original operation instead of creating another sandbox under a new key. A name is descriptive rather than a promise of uniqueness or an instruction to restore an old environment. The current image field is passed into ownership environment metadata by the adapter, so do not assume it provides an arbitrary image-selection capability without verifying the configured provider behavior.

Inspect status before dependent work

List containers to observe provider status and accumulated usage_seconds. The API maps common provider states into running, stopped, starting or error, but can return unknown when a provider lookup fails. Unknown is not proof that a workload has stopped. Before requesting a desktop shell, ensure the resource is running; that route explicitly rejects a stopped container. Before running a command, keep the runtime lease live and the required update permission available. A successful create response does not establish that every installed dependency or application server is ready for your next step.

curl -X POST https://api.lupin.sh/v0/containers \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  -H "Idempotency-Key: artifact-sandbox-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"artifact-task","timeout_seconds":120}'

Run small observable stages

Execute a bounded command, inspect status, exit_code, stdout and stderr, then verify the expected output. Keep input files and generated artifacts in explicit paths. The command route is synchronous, and the provider adapter bounds requested command timeouts rather than exposing a durable job scheduler. When durable storage is enabled, command requests need a preserved Idempotency-Key; raw HTTP clients must send it explicitly. A lost command result can have an unknown effect, so use run history and current files before submitting a replacement. The lifecycle should make these intermediate observations visible to the task runner.

Export before stopping and verify closure

Download the needed small artifact or use an approved external storage path before stopping. Stop requires update permission and an idempotency key; the implementation verifies provider closure before settling the completed runtime interval. If that request fails, retain cleanup uncertainty instead of reporting the whole task complete. Stop and resume are supported, while deletion and port revocation are not exposed. A later resume is a provider lifecycle action, not a guarantee that a running process continues untouched. Keep the final artifact and verification record independently of the sandbox so the user can review the work after runtime ends.

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 · quickstart ↗Checked 2026-11-05
• docs.boat.dev · snapshots · stop ↗Checked 2026-11-05

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