Plan an agent compute task before allocating runtime

Begin with the deliverable

Describe what the user should receive: a validated data file, a built preview or a diagnostic finding supported by evidence. Then identify why hosted execution is needed. Some work can be completed by reading local files or reviewing an API contract without allocating compute. When a sandbox is appropriate, write the expected output format and acceptance check before creation. This makes the task concrete enough to budget and prevents the agent from treating command execution itself as progress. A sequence of successful shell calls is not useful if it never produces the requested result.

Resolve authority and readiness early

Check workspace capability, human verification, required container permissions, billing eligibility and provider configuration. The hosted surface depends on BOAT_API_KEY; it is distinct from an optional consumer-agent Cloudflare execution backend. A bootstrap registration key cannot create paid resources. Missing authority is not solved by trying another wrapper around the same endpoint. Prepare the inputs and reviewed script while independent work can continue, then let the authorized owner resolve any external prerequisite. Do not allocate a resource just to discover that the task lacks its input file or necessary application permission.

Design observable stages

Use a short sequence such as inspect environment, verify input, execute transformation, validate output, export artifact and stop resource. Give each stage a clear output and failure condition. Keep explicit paths and preserve Idempotency-Key values for creation, lifecycle changes and durable command-backed mutations. The current synchronous command interface does not provide a general job scheduler, so the task runner must retain progress and uncertainty. A stage that has an unknown effect needs reconciliation before a replacement attempt. Avoid mixing local pure computation and consequential network actions in one opaque command when they can be reviewed separately.

{"name":"reviewable-task","timeout_seconds":120}

Allocate time for evidence and recovery

Estimate setup and dependency work as well as the main job. Leave room to inspect exit status, parse the artifact, transfer it and confirm cleanup. Command timeouts, provider request deadlines and total resource runtime are separate constraints. A lost response may not mean the process stopped. Define a partial-completion policy: which verified intermediate artifact is useful, what must remain unfinished and how to report it. Do not promise unlimited background continuation or durable process checkpointing. A saved task manifest supports later work, but it does not preserve every running process or external connection.

Close with a reviewable result

The final result should name the artifact, explain the meaningful check performed and state any unresolved limit. Report source review as source review and actual fixture execution as tested behavior. Keep secrets and temporary desktop links out of the summary. Save needed artifacts independently of the sandbox and stop idle runtime; the current API exposes stop and resume rather than general deletion or port revocation. If cleanup is uncertain, report it separately from the computation's success. A planned compute task ends with evidence the user can inspect and an honest resource state, not an invitation to guess what remains running.

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.