> ## Documentation Index
> Fetch the complete documentation index at: https://modal-computer-use.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"system"}
uv add "modal-computer-use[modal]"
```

Authenticate the Modal CLI on your workstation:

```bash theme={"system"}
uv run modal setup
```

## Create and own a desktop

```python theme={"system"}
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:

```python theme={"system"}
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](https://github.com/ashtonchew/modal-computer-use/blob/main/examples/modal_function_session_handoff.py) 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.

<Warning>
  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.
</Warning>

## Clean up stale desktops

Inspect a cleanup plan before you terminate anything:

```python theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.