Create, attach, and borrow

Choose the lifecycle and cleanup contract for one Modal desktop.

Create an owner for the primary path

AsyncComputerSandbox.create() requires an explicit Modal environment and a supported narrow or Workspace-granted granular region selector. It also requires an ingress and ownership mode that can produce a session handle. Invalid handoff settings fail before Modal allocation.

from modal_computer_use import AsyncComputerSandbox, ComputerConfig

config = ComputerConfig(
    runtime={"modal_environment": "main", "modal_region": "us-west"},
    resources={"profile": "browser", "cpu": 1.0, "memory_mib": 2048},
    browser={"kind": "chromium"},
)

async with AsyncComputerSandbox.create(config=config, app_name="my-app") as owner:
    handle = owner.session_handle()

The owner terminates its desktop on exit. Keep it open until every dispatched Function call reaches a terminal outcome.

Borrow inside the placed Function

async with handle.borrow_async(
    run_id=run_id,
    function_region="us-west",
) as computer:
    initial = await computer.screenshots.full()
    step = await computer.step(actions)

Borrowing acquires one trajectory lease and one pooled client. It verifies placement, readiness, protocol capabilities, and policy before mutation. The borrower releases the lease and detaches. It never terminates the owner’s desktop.

Attach without ownership

Use one explicit selector when a desktop already has an owner:

from modal_computer_use import ComputerSandbox

with ComputerSandbox.attach(sandbox_id=sandbox_id, wait=True) as computer:
    status = computer.lifecycle.status()

An attached context closes its connection on exit and leaves the Sandbox running.

Use an explicit low-level owner

AsyncComputerSandbox.create_unplaced() supports compatibility workflows with caller-owned topology. Local clients and direct daemon clients remain available for debugging and REST use.

Keep cleanup order stable

1. Stop new mutations.
2. Resolve or seal an ambiguous outcome.
3. Close the borrowed client and release its lease.
4. Wait for the Function call to reach a terminal state.
5. Close the owner client and terminate the owned Sandbox.

Cancellation leaves any input that reached the desktop in place for explicit recovery.