Cua Computer Server

0.3.32 · active · verified Sun Apr 12

The `cua-computer-server` is the server component for the Computer-Use Interface (CUI) framework, enabling AI agents to programmatically control a host desktop. It runs as a local HTTP service, exposing endpoints for screenshots, mouse/keyboard input, and other computer operations across macOS, Linux, and Windows. As of version 0.3.32, it forms a core part of the Cua ecosystem, facilitating direct machine interaction for agent development and testing.

Warnings

breaking The computer server grants full programmatic control over your desktop. Exposing it to public networks without proper security measures is a critical risk, as anyone who can reach the server can take screenshots, control input, and launch applications.
Fix: Only run the server on localhost or trusted, private networks. Do not expose to the public internet. Stop the server when not actively in use. Consider using sandboxes for untrusted workloads.
gotcha When running on Retina displays or in virtual machines, coordinate systems may differ. Failing to specify a target resolution can lead to misaligned clicks or inaccurate screenshot representations for AI agents.
Fix: Start the server with `--width` and `--height` flags to specify the target resolution (e.g., `python -m computer_server --width 1512 --height 982`). This ensures consistent coordinate scaling between screenshots and input actions.
gotcha Client-side interaction with `cua-computer-server` requires the separate `cua` Python package. Attempting to use the server without the `cua` package for client connections will result in import errors or missing functionality.
Fix: Ensure the `cua` library is installed alongside `cua-computer-server` if you plan to control the server programmatically (e.g., `pip install cua cua-computer-server`).
gotcha Connection issues such as 'Connection refused' or 'Port already in use' are common if the server isn't running, the port is occupied, or firewall rules block the connection.
Fix: Verify the server is running (`python -m computer_server`). Check if the default port (8000) is in use and either free it or start the server on a custom port (`--port <number>`). Ensure firewall rules allow the connection.
breaking The library explicitly requires Python versions between 3.12 and 3.14 (exclusive of 3.14). Using Python 3.11 or older, or Python 3.14 or newer, will prevent installation or lead to unexpected behavior.
Fix: Ensure your Python environment is running Python >=3.12 and <3.14. [PyPI metadata]

Install

pip install cua-computer-server Basic installation
pip install cua-computer-server[mcp] With MCP support

Imports

computer_server
```
python -m computer_server
```
The cua-computer-server is typically run as a module, not imported as a Python library for direct class instantiation.
Sandbox, Image, ComputerAgent
```
from cua import Sandbox, Image, ComputerAgent
```
To connect to and control the server from a Python agent, these symbols are imported from the 'cua' library, not 'cua-computer-server' directly.

Quickstart

To use `cua-computer-server`, first run the server as a Python module in a terminal. Then, connect to it from a Python script using the `cua` library's `Sandbox.create()` method with `use_host_computer_server=True`. The example demonstrates connecting and taking a screenshot.

import asyncio
import os
from cua import Sandbox

async def main():
    # Make sure to start the server first in a separate terminal:
    # python -m computer_server --port 8000 --log-level debug
    
    # For this example, we assume the server is running on localhost:8000
    # You might need to adjust api_host and api_port if running elsewhere.
    try:
        async with Sandbox.create(
            use_host_computer_server=True,
            api_host=os.environ.get('CUA_SERVER_HOST', 'localhost'),
            api_port=int(os.environ.get('CUA_SERVER_PORT', 8000))
        ) as computer:
            print("Connected to local computer server.")
            
            # Take a screenshot
            screenshot = await computer.interface.screenshot()
            print(f"Screenshot captured: {screenshot.format}")
            
            # Example: Left click at (500, 300) and type text
            # await computer.interface.left_click(500, 300)
            # await computer.interface.type_text("Hello from the agent!")
            # print("Performed click and typed text.")
            
    except Exception as e:
        print(f"Error connecting to computer server: {e}")
        print("Please ensure the computer server is running: 'python -m computer_server'")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →