{"id":4920,"library":"cua-computer-server","title":"Cua Computer Server","description":"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.","status":"active","version":"0.3.32","language":"en","source_language":"en","source_url":"https://github.com/trycua/cua/tree/main/libs/python/computer-server","tags":["AI agents","desktop automation","CUI","computer control","sandbox","HTTP server","automation"],"install":[{"cmd":"pip install cua-computer-server","lang":"bash","label":"Basic installation"},{"cmd":"pip install cua-computer-server[mcp]","lang":"bash","label":"With MCP support"}],"dependencies":[{"reason":"Core server dependency for running the HTTP service.","package":"uvicorn","optional":false},{"reason":"Core server dependency for the HTTP API.","package":"fastapi","optional":false},{"reason":"Required for client-side interaction with the computer server from Python agents.","package":"cua","optional":false},{"reason":"Required for the 'mcp' extra to enable Model Context Protocol support.","package":"fastmcp","optional":true},{"reason":"Requires Python version 3.12 or 3.13.","package":"python","optional":false}],"imports":[{"note":"The cua-computer-server is typically run as a module, not imported as a Python library for direct class instantiation.","symbol":"computer_server","correct":"python -m computer_server"},{"note":"To connect to and control the server from a Python agent, these symbols are imported from the 'cua' library, not 'cua-computer-server' directly.","symbol":"Sandbox, Image, ComputerAgent","correct":"from cua import Sandbox, Image, ComputerAgent"}],"quickstart":{"code":"import asyncio\nimport os\nfrom cua import Sandbox\n\nasync def main():\n    # Make sure to start the server first in a separate terminal:\n    # python -m computer_server --port 8000 --log-level debug\n    \n    # For this example, we assume the server is running on localhost:8000\n    # You might need to adjust api_host and api_port if running elsewhere.\n    try:\n        async with Sandbox.create(\n            use_host_computer_server=True,\n            api_host=os.environ.get('CUA_SERVER_HOST', 'localhost'),\n            api_port=int(os.environ.get('CUA_SERVER_PORT', 8000))\n        ) as computer:\n            print(\"Connected to local computer server.\")\n            \n            # Take a screenshot\n            screenshot = await computer.interface.screenshot()\n            print(f\"Screenshot captured: {screenshot.format}\")\n            \n            # Example: Left click at (500, 300) and type text\n            # await computer.interface.left_click(500, 300)\n            # await computer.interface.type_text(\"Hello from the agent!\")\n            # print(\"Performed click and typed text.\")\n            \n    except Exception as e:\n        print(f\"Error connecting to computer server: {e}\")\n        print(\"Please ensure the computer server is running: 'python -m computer_server'\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is running Python >=3.12 and <3.14. [PyPI metadata]","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}