Run your first placed trajectory

Create one desktop and lend it to one placed Modal Function.

This quickstart keeps the desktop owner outside the Function. The Function borrows the desktop once for the complete trajectory.

Set explicit application choices

Use one supported region selector for the Function and Sandbox. This example uses the public narrow selector us-west. You can use a Workspace-granted granular selector such as us-west-2 when your Modal Workspace supports it.

import modal
from modal_computer_use import AsyncComputerSandbox, ComputerConfig, ComputerSessionHandle

APP_NAME = "computer-use-quickstart"
ENVIRONMENT = "main"
REGION = "us-west"

app = modal.App(APP_NAME)
image = modal.Image.debian_slim(python_version="3.12").pip_install(
    "modal-computer-use[modal]==2.0.2"
)

Define the placed Function

Keep your model call in this Function. The placeholder action below lets the example compile without a provider SDK.

@app.function(
    image=image,
    region=REGION,
    cpu=1.0,
    memory=2048,
    retries=0,
    min_containers=0,
    max_containers=4,
    timeout=900,
)
async def run_trajectory(handle: ComputerSessionHandle, run_id: str):
    async with handle.borrow_async(run_id=run_id, function_region=REGION) as computer:
        screenshot = await computer.screenshots.full(format="png")
        actions = [{"type": "wait", "duration_ms": 50}]
        step = await computer.step(actions, continue_on_error=False)
        screenshot = step.screenshot
        return {"status": "succeeded", "sha256": screenshot.sha256}

Create and own the desktop

import uuid

config = ComputerConfig(
    ingress="attested-tunnel",
    runtime={
        "modal_environment": ENVIRONMENT,
        "modal_region": REGION,
        "timeout_seconds": 900,
        "readiness_timeout_seconds": 120,
    },
    resources={"profile": "browser", "cpu": 1.0, "memory_mib": 2048},
    image={"source": "inline"},
    browser={"kind": "chromium", "prewarm": False},
)

async with AsyncComputerSandbox.create(config=config, app_name=APP_NAME) as owner:
    handle = owner.session_handle()
    result = await run_trajectory.remote.aio(handle, f"trajectory_{uuid.uuid4().hex}")

The owner waits for the Function result before it closes. Borrow cleanup runs first. Owner cleanup then terminates the desktop. Modal can report a provider-native runtime region such as us-west-2, us-west1, or westus3 for the public us-west selector.

Deploy the Function

Save the code in one module, then deploy it to the same explicit environment:

uv run modal deploy --env main quickstart.py

Invoking the Function and creating the Sandbox can incur Modal charges. Warm capacity remains off because min_containers=0 and this example creates no Sandbox pool.

Use the maintained session-handoff example for cancellation, spawning, resolved configuration, and recovery handling.