Deploy a Modal desktop

Create, attach, hand off, and clean up Modal desktop Sandboxes.

Use ComputerSandbox.create() for a new synchronous desktop. Use AsyncComputerSandbox.create() in an asyncio application.

Install the Modal extra

uv add "modal-computer-use[modal]"

Authenticate the Modal CLI on your workstation:

uv run modal setup

Create and own a desktop

from modal_computer_use import ComputerConfig, ComputerSandbox

with ComputerSandbox.create(config=ComputerConfig()) as computer:
    status = computer.lifecycle.status()

The SDK starts the daemon on port 8080. Modal waits for TCP readiness. The default create call also waits for /readyz before it yields the desktop.

/healthz proves that the daemon process is alive. /readyz also checks the desktop dependencies.

The created context owns the Sandbox. It terminates the Sandbox and closes the connection on exit.

Attach without taking ownership

Use exactly one selector:

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

You can select by sandbox_id, name, run_id, or direct base_url. A direct URL does not resolve a Modal Sandbox.

An attached context closes its connection on exit. It does not terminate the remote owner’s Sandbox.

Use attach_or_create(name=...) when one app needs one compatible named desktop. Modal enforces name uniqueness within the App. The SDK checks the app and configuration tags before reuse.

Select ingress

Ingress	Behavior	Use
attested-tunnel	Mints a short-lived session token from an SDK-managed bootstrap token.	Default desktop traffic.
connect	Keeps daemon traffic on Modal Connect.	Blocked network or Connect-only policy.
tunnel	Uses the bootstrap bearer directly.	Trusted benchmark harnesses.

Keep attested-tunnel unless your deployment has a measured or policy requirement.

Hand a session to a Modal Function

Use a deployed Modal Function for a repeated model and desktop trajectory.

Create the desktop with an explicit runtime.modal_region. Use attested-tunnel or connect ingress. Keep VNC off or view-only.

1. Create the desktop in the owner process.
2. Call session_handle() on the owner.
3. Pass the handle to the deployed Function.
4. Enter one borrow_async() context for the complete trajectory.
5. Wait for the Function outcome.
6. Terminate the desktop in the owner process.

Set the same measured region selector on the desktop and the Function. Pass that value to borrow_async(function_region=...).

Use retries=0 for the stateful Function. A platform retry still does not make a GUI trajectory exactly once.

The session handoff example shows how an owner lends one desktop to a deployed Function. Use it when the Function needs a complete stateful trajectory. The owner remains responsible for lifetime and ambiguous outcomes.

The owner must keep the target running until each remote or spawned Function call reaches a terminal outcome. Function cancellation does not undo prior input. It also does not terminate the desktop.

Clean up stale desktops

Inspect a cleanup plan before you terminate anything:

from modal_computer_use import ComputerSandboxManager

manager = ComputerSandboxManager()
plan = manager.cleanup_expired(
    ttl_seconds=3600,
    owner="worker",
    dry_run=True,
)

Set dry_run=False only after you review the plan. The manager skips a Sandbox when it cannot prove the creation time or app ownership.