Understand a sandbox’s isolation and authority

Isolation is an execution boundary

Lupin's hosted container surface delegates execution to Boat sandboxes. It is separate from the consumer agent's optional Cloudflare sandbox and from Cloudflare Browser Run sessions. Choose the hosted container when the task needs shell commands, files or an application process. Isolation helps separate that workload from the API service, but it does not decide whether an agent's command is authorized. A command can still contact an external system, overwrite its own working files or expose data through a server. Define the allowed workload before granting the agent an execution tool.

Keep platform secrets outside the workload

The Boat adapter creates user sandboxes with noEnv true and adds explicit ownership tags such as LUPIN_ORG_ID and LUPIN_CONTAINER_NAME. That prevents automatic inheritance of the operator's configured environment. Do not treat it as a promise that every command or uploaded file is secret-free. Your application can still introduce credentials through command strings, configuration files or dependencies. Give the workload only the narrowly scoped credentials it needs, and avoid including provider account keys. The caller's Lupin API key should authenticate the control request rather than become a file inside the sandbox.

Use workspace ownership and permissions

Container routes look up resources under the caller's organization and separate read, create and update permissions. Human verification, billing eligibility and a configured BOAT_API_KEY are additional prerequisites for paid execution. A bootstrap registration key cannot create a sandbox merely because it can read platform information. Store container_id with the task and use that exact resource identity for later commands and cleanup. Names help humans recognize a workload but do not replace organization ownership checks. A stale or guessed identifier should not cause the agent to search for another customer's execution environment.

{"name":"analysis-task"}

Control the edges of the environment

The public API includes synchronous commands, small file transfer, port publication and a temporary desktop-shell URL. Each edge needs its own policy. Publishing a port creates a public HTTPS endpoint, so the hosted application needs authentication before private data is available there. A shell URL carries access credentials and should not enter shared logs. The API does not expose a general network-policy configuration or a port-revocation endpoint. Do not imply those controls exist because the provider has a broader product catalog. Evaluate the actual Lupin surface the task will use.

Verify the workload and close the resource

A successful HTTP command response can contain a nonzero exit_code, so inspect the command result and its files before accepting an output. Save required artifacts outside the sandbox and stop idle runtime after the task. Stopping and resuming are supported, while deletion is not exposed through the current container API. Neither a sandbox name nor isolation alone establishes reproducibility, durable retention or a particular machine size. Record the environment observations, dependencies and verification method that actually support the result. Isolation is most useful when paired with explicit authority, minimal secrets and deliberate lifecycle control.

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 · security ↗Checked 2026-11-05
• docs.boat.dev · environments · access ↗Checked 2026-11-05

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