> ## 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.

# 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

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

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

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

<Warning>
  Call `terminate()` on an attached desktop only when your process has authority to stop its owner's Sandbox.
</Warning>

## Acquire a named desktop

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

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

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


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