modal-computer-use

modal-computer-use turns a Modal Sandbox into a remotely controllable Linux desktop through a typed, provider-neutral Python SDK and an in-Sandbox daemon.

This is an independent project using Modal.

Quick start

Use Python 3.12 or later and uv. Install the Modal extra from PyPI:

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

The Modal extra supports the Modal 1.5 line and requires Modal 1.5.2 or later.

Save this as quickstart.py:

from modal_computer_use import (
    BrowserConfig,
    ComputerConfig,
    ComputerSandbox,
    ResourceConfig,
)

config = ComputerConfig(
    resources=ResourceConfig(profile="browser"),
    browser=BrowserConfig(kind="chromium"),
)

with ComputerSandbox.create(config=config) as computer:
    computer.browser.open_url("https://example.com")
    computer.mouse.move(320, 240)
    screenshot = computer.screenshots.full()
    screenshot.save("screenshot.png")
    print(screenshot.width, screenshot.height, screenshot.sha256)

Run it:

uv run python quickstart.py

When the with block ends, the SDK terminates the Sandbox and closes the connection.

Core API

ComputerSandbox is the primary synchronous entry point. AsyncComputerSandbox provides native async Modal creation, attachment, and named acquisition with the same ownership rules; see the async owner example. AsyncDaemonClient connects to an existing daemon without blocking the event loop.

Action batches validate the full request before execution. They stop on the first error by default, can opt into continue_on_error, and can capture a trailing screenshot in the same request.

Inside an active ComputerSandbox:

batch = computer.actions.run(
    [
        {"type": "move", "x": 320, "y": 240},
        {"type": "click", "x": 320, "y": 240},
    ],
    screenshot_after=True,
)

batch.screenshot contains the trailing observation when the batch succeeds.

See the API guide for namespace semantics and the generated OpenAPI schema for HTTP request and response shapes.

How it works

ComputerSandbox.create() starts a new Modal Sandbox. If you use it in a with block, the SDK terminates the Sandbox automatically when the block ends. ComputerSandbox.attach() connects to an existing Sandbox. Leaving an attached with block closes the SDK connection but keeps the Sandbox running.

ComputerSandbox.attach_or_create(name=...) and its async counterpart acquire a compatible live Sandbox with that app-scoped name, or create one if it is missing. If the call creates the Sandbox, leaving the block terminates it. If the Sandbox already existed, leaving the block keeps it running.

A daemon inside the Sandbox executes desktop actions, captures screenshots and recordings, runs commands, and reads or writes files through computer.artifacts.

Performance

The figure shows July 2026 p50 latency for six computer-use cases, based on 30 successful samples per cell. Lower is better. Note that warm-operation latency starts after the desktop and client connection are ready.

The detailed report gives p95 results and explains how each path was configured and measured.

Examples

Documentation

Local development

See the local development guide for daemon startup, mock and X11 backends, synchronous and async clients, authentication, and repository checks.

Security

The daemon can control the desktop and access clipboard contents, screenshots, recordings, and artifacts. Do not expose it without authentication.

See the security policy for reporting vulnerabilities and the runtime security guide for deployment guidance.