lupin.Open console
Sandboxes

Choose a browser or sandbox for the actual task

Match page interaction to Browser Run and command execution to hosted containers without inventing cross-product capabilities.

Lupin editorialAI-assisted3 min read

Choose the interface the task needs

Use a browser when the work depends on a rendered website, visible controls, tabs, screenshots or an authorized human sign-in. Use a hosted sandbox when the work needs shell commands, files, dependencies or an application process. Lupin's browsers use Cloudflare Browser Run, while the hosted container surface uses the configured Boat provider. They are separate products with different permissions, lifecycle and outputs. A browser is not an arbitrary code-execution endpoint, and a sandbox is not automatically a managed authenticated browser. Start from the task's necessary interface instead of choosing whichever tool name sounds more powerful.

Use research for a small public question

For a known public document, the browser research read operation creates a bounded temporary session and closes it afterward. Search adds a configured Composio search action before Cloudflare source reading. That can be the appropriate choice for evidence gathering without keeping interactive page state alive. The fixed browser action surface includes navigation, reads, controls and screenshots, while downloads and arbitrary evaluation are disabled. Public URL validation rejects private destinations and custom ports. If the task only needs a public fact, allocating a general shell environment may introduce unnecessary setup and network authority.

Use compute for file and program work

A container can run a script, transform uploaded data and produce an artifact. Inspect its actual runtime and dependencies, then verify exit_code, stdout, stderr and the resulting file. Small files move through base64 routes with roughly two-megabyte limits; larger artifacts need another approved storage path. Port publication creates a public HTTPS endpoint and requires application authentication for private data. Do not assume the image field selects an arbitrary machine image or that a provider's machine-size catalog is exposed through Lupin. The public contract provides specific execution and lifecycle operations, not every upstream feature.

Illustrative request; source reviewed, not executed against a live provider.
// Public evidence from a known URL:
const page = await lupin.browsers.read(
  "https://example.com", "public-document-001"
);
// Choose a separately authorized container stage only if execution is needed.

Keep authority separate in either product

Both paid browser and compute allocation require human verification, workspace permissions, billing readiness and provider availability. The bootstrap key is limited to reading, email and drafts and cannot create these resources. Browser website sign-in is another boundary, typically completed by an authorized human in a private live view. Container workload credentials should be narrowly scoped; the adapter uses noEnv true to avoid inheriting operator secrets. Custom Lupin proxy routing is not supported for the current Browser Run provider, so owning a proxy user does not make it available as a browser creation option.

Combine products through explicit artifacts

Some tasks need both: research public documentation, then run a local transformation using the gathered requirements. Pass a clear evidence record or input artifact between stages instead of assuming shared cookies, files or runtime. Preserve separate resource identities, operation keys and cleanup results. Browser sessions do not persist profiles after closure; container stop and resume do not promise arbitrary in-memory checkpointing. Save the useful outputs outside each resource and close idle runtime promptly. The right choice is the smallest authorized interface that can produce the required evidence and artifact with a clear verification path.

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.

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

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore containers