Create and attach to desktops

Choose a Modal Sandbox lifecycle and keep ownership explicit.

Use create() when your process owns a new desktop. Use attach() when another process owns an existing desktop.

Create an owned desktop

from modal_computer_use import ComputerSandbox

with ComputerSandbox.create() as computer:
    status = computer.status()
    print(status.ready)

The context waits for daemon readiness. It terminates the created Sandbox on exit.

Set wait=False when you need to do other work before readiness:

computer = ComputerSandbox.create(wait=False)
try:
    computer.wait_until_ready(timeout=120.0)
    print(computer.status().ready)
finally:
    computer.terminate(wait=True)
    computer.detach()

Attach without taking ownership

Pass exactly one selector. You can use sandbox_id, name, or run_id for a Modal-backed attachment.

from modal_computer_use import ComputerSandbox

computer = ComputerSandbox.attach(
    sandbox_id="sb-REPLACE_ME",
    wait=True,
    readiness_timeout=120.0,
)
try:
    print(computer.status().ready)
finally:
    computer.detach()

detach() closes the daemon connection and releases the local Modal handle. It does not terminate the attached Sandbox.

Call terminate() on an attached desktop only when your process has authority to stop its owner’s Sandbox.

Acquire a named desktop

Use attach_or_create() when a name is your allocation key:

from modal_computer_use import ComputerConfig, ComputerSandbox

with ComputerSandbox.attach_or_create(
    name="support-desktop",
    config=ComputerConfig(),
) as computer:
    print(computer.status().ready)

The SDK attaches to a compatible live Sandbox with that app-scoped name. It creates one if none exists. The context terminates only a Sandbox that this call created.

An existing named Sandbox must match the expected configuration tags. Use attach(name=...) when you intentionally connect to a legacy target.

Use native async lifecycle methods

The async lifecycle methods are async context managers:

import asyncio

from modal_computer_use import AsyncComputerSandbox


async def main() -> None:
    async with AsyncComputerSandbox.create() as computer:
        screenshot = await computer.screenshots.full()
        print(screenshot.width, screenshot.height)


asyncio.run(main())

Do not await AsyncComputerSandbox.create() directly. Enter the returned context manager with async with.

Lifecycle summary

Construction path	Context exit
create()	Terminates and detaches the created Sandbox
attach()	Detaches and keeps the existing Sandbox running
Existing branch of attach_or_create()	Detaches and keeps the existing Sandbox running
Created branch of attach_or_create()	Terminates and detaches the created Sandbox
local() or direct base_url	Closes the daemon connection only