lupin.Open console
Browsers

Plan concurrent browser work with separate sessions

Choose isolation boundaries, avoid conflicting controllers and respect workspace and provider capacity.

Lupin editorialAI-assisted3 min read

Choose isolation before increasing concurrency

Use separate sessions when tasks need different website accounts, independent cookies or unrelated page state. Multiple tabs inside one session are a convenience for related work, not a substitute for an isolation boundary between customers. A session is registered to one workspace, and browser state remains temporary. Decide which tasks can safely share a browser before optimizing throughput. Running more sessions can increase runtime consumption and capacity pressure without improving an overloaded target website. Concurrency should follow the dependency structure of the work rather than the number of tasks waiting in a queue.

Check both workspace and provider limits

The capabilities endpoint indicates provider readiness, while billing entitlement and current runtime reservations determine whether the workspace can allocate another browser. Cloudflare capacity also applies. A workspace with valid credentials can still receive a capacity or billing restriction. Do not infer unlimited concurrency from an API key with create permission. In an enforced workspace, Lupin reserves finite runtime and capacity before provider allocation. The Free shared browser pool can be busy, and some plans may not include the resource. Treat these results as scheduling inputs rather than reasons to generate new allocation keys repeatedly.

Give each allocation a task identity

Create a unique stable Idempotency-Key for each intended session and preserve it across retries of that allocation. Store session_id with the owning task, account context and cleanup state. A second worker must not accidentally reuse the first worker's key with a different name or runtime. Conversely, a lost create response must not cause the scheduler to generate a new key and allocate an extra browser. Keep a bounded queue and assign ownership of finalization. The worker that fails to complete its page task still needs to report or reconcile the resource it started.

Illustrative request; source reviewed, not executed against a live provider.
// Use a distinct preserved key for each intended allocation.
const session = await lupin.browsers.create(
  { name: "source-task-a", timeout_seconds: 60 },
  "source-task-a-allocation-001"
);

Use one controller per mutable page

Two agents clicking or filling the same tab can invalidate each other's observations between read and action. Human takeover creates the same coordination problem. Assign a single controller while a tab is being changed, and refresh the page observation when control transfers. Parallel reading of independent documents can be sensible, but shared authentication and navigation history still need care. Explicit tab_id values prevent accidental default targeting; they do not serialize competing actions or make a multi-step form transaction atomic. Use an application-level lock or workflow ownership rule when shared session state matters.

Measure useful completion instead of session count

Track completed evidence tasks, unresolved actions, runtime and confirmed cleanup. A browser that waits for an operator still occupies capacity, so reserve time for that handoff or release the session when the wait cannot fit. End independent sessions as their work finishes rather than keeping the whole batch alive until its slowest task completes. Save findings outside the browser because closed sessions cannot resume their cookies. If a target site signals overload or access restrictions, reduce or stop concurrency according to its rules. The useful performance measure is authorized work completed with clear evidence and closed resources, not browsers opened per minute.

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 browsers