Cua Computer Interface for cross-platform computer control.

Classes

Computer

Computer is the main class for interacting with the computer.

Methods

Computer.create_desktop_from_apps

def create_desktop_from_apps(self, apps)

Create a virtual desktop from a list of app names, returning a DioramaComputer that proxies Diorama.Interface but uses diorama_cmds via the computer interface.

Args: apps (list[str]): List of application names to include in the desktop. Returns: DioramaComputer: A proxy object with the Diorama interface, but using diorama_cmds.

Computer.run

async def run(self) -> Optional[str]

Initialize the VM and computer interface.

Computer.disconnect

async def disconnect(self) -> None

Disconnect from the computer's WebSocket interface.

Computer.stop

async def stop(self) -> None

Disconnect from the computer's WebSocket interface and stop the computer.

Computer.start

async def start(self) -> None

Start the computer.

Computer.restart

async def restart(self) -> None

Restart the computer.

If using a VM provider that supports restart, this will issue a restart without tearing down the provider context, then reconnect the interface. Falls back to stop()+run() when a provider restart is not available.

Computer.get_ip

async def get_ip(self, max_retries: int = 15, retry_delay: int = 3) -> str

Get the IP address of the VM or localhost if using host computer server.

This method delegates to the provider's get_ip method, which waits indefinitely until the VM has a valid IP address.

Args: max_retries: Unused parameter, kept for backward compatibility retry_delay: Delay between retries in seconds (default: 2)

Returns: IP address of the VM or localhost if using host computer server

Computer.wait_vm_ready

async def wait_vm_ready(self) -> Optional[Dict[str, Any]]

Wait for VM to be ready with an IP address.

Returns: VM status information or None if using host computer server.

Computer.update

async def update(self, cpu: Optional[int] = None, memory: Optional[str] = None)

Update VM settings.

Computer.get_screenshot_size

def get_screenshot_size(self, screenshot: bytes) -> Dict[str, int]

Get the dimensions of a screenshot.

Args: screenshot: The screenshot bytes

Returns: Dict[str, int]: Dictionary containing 'width' and 'height' of the image

Computer.to_screen_coordinates

async def to_screen_coordinates(self, x: float, y: float) -> tuple[float, float]

Convert normalized coordinates to screen coordinates.

Args: x: X coordinate between 0 and 1 y: Y coordinate between 0 and 1

Returns: tuple[float, float]: Screen coordinates (x, y)

Computer.to_screenshot_coordinates

async def to_screenshot_coordinates(self, x: float, y: float) -> tuple[float, float]

Convert screen coordinates to screenshot coordinates.

Args: x: X coordinate in screen space y: Y coordinate in screen space

Returns: tuple[float, float]: (x, y) coordinates in screenshot space

Computer.playwright_exec

async def playwright_exec(self, command: str, params: Optional[Dict] = None) -> Dict[str, Any]

Execute a Playwright browser command.

Args: command: The browser command to execute (visit_url, click, type, scroll, web_search) params: Command parameters

Returns: Dict containing the command result

Examples: # Navigate to a URL await computer.playwright_exec("visit_url", {"url": "https://example.com"\})

Click at coordinates

await computer.playwright_exec("click", {"x": 100, "y": 200})

Type text

await computer.playwright_exec("type", {"text": "Hello, world!"})

Scroll

await computer.playwright_exec("scroll", {"delta_x": 0, "delta_y": -100})

Web search

await computer.playwright_exec("web_search", {"query": "computer use agent"})

Computer.venv_install

async def venv_install(self, venv_name: str, requirements: list[str])

Install packages in a UV project.

Args: venv_name: Name of the UV project requirements: List of package requirements to install

Returns: Tuple of (stdout, stderr) from the installation command

Computer.pip_install

async def pip_install(self, requirements: list[str])

Install packages using the system Python with UV (no venv).

Args: requirements: List of package requirements to install globally/user site.

Returns: Tuple of (stdout, stderr) from the installation command

Computer.venv_cmd

async def venv_cmd(self, venv_name: str, command: str)

Execute a shell command in a UV project.

Args: venv_name: Name of the UV project command: Shell command to execute in the UV project

Returns: Tuple of (stdout, stderr) from the command execution

Computer.venv_exec

async def venv_exec(self, venv_name: str, python_func, args = (), kwargs = {})

Execute Python function in a virtual environment using source code extraction.

Args: venv_name: Name of the virtual environment python_func: A callable function to execute *args: Positional arguments to pass to the function **kwargs: Keyword arguments to pass to the function

Returns: The result of the function execution, or raises any exception that occurred

Computer.venv_exec_background

async def venv_exec_background(self, venv_name: str, python_func, args = (), requirements: Optional[List[str]] = None, kwargs = {}) -> int

Run the Python function in the venv in the background and return the PID.

Uses a short launcher Python that spawns a detached child and exits immediately.

Computer.python_exec

async def python_exec(self, python_func, args = (), kwargs = {})

Execute a Python function using the system Python (no venv).

Uses source extraction and base64 transport, mirroring venv_exec but without virtual environment activation.

Returns the function result or raises a reconstructed exception with remote traceback context appended.

Computer.python_exec_background

async def python_exec_background(self, python_func, args = (), requirements: Optional[List[str]] = None, kwargs = {}) -> int

Run a Python function with the system interpreter in the background and return PID.

Uses a short launcher Python that spawns a detached child and exits immediately.

Computer.python_command

def python_command(self, requirements: Optional[List[str]] = None, venv_name: str = 'default', use_system_python: bool = False, background: bool = False) -> Callable[[Callable[P, R]], Callable[P, Awaitable[R]]]

Decorator to execute a Python function remotely in this Computer's venv.

This mirrors computer.helpers.sandboxed() but binds to this instance and optionally ensures required packages are installed before execution.

Args: requirements: Packages to install in the virtual environment. venv_name: Name of the virtual environment to use. use_system_python: If True, use the system Python/pip instead of a venv. background: If True, run the function detached and return the child PID immediately.

Returns: A decorator that turns a local function into an async callable which runs remotely and returns the function's result.

VMProviderType

Enum of supported VM provider types.