cua-computer vs cua-computer-server: Understanding the Client-Server Architecture

The cua-computer package is a client-side SDK that sends high-level commands to a remote machine, while cua-computer-server is the service that runs inside a sandbox or host OS to execute those low-level actions.

Both packages are part of the trycua/cua open-source project, which provides Python libraries for AI-driven computer automation. Understanding their distinct roles is essential for building applications that control remote desktops, sandboxes, or virtual machines through a clean client-server model.

What Is cua-computer?

cua-computer is the client-side SDK that developers import into their Python applications to communicate with a running computer server. It abstracts the complexity of network communication behind a high-level Computer object, offering intuitive methods for screenshots, mouse control, keyboard input, and file operations.

Core Responsibilities and Entry Points

The primary implementation resides in libs/python/computer/computer/computer.py, which contains the Computer class. This class manages session lifecycle, handles connection pooling, and proxies method calls to the server over HTTP/WebSocket or MCP (Model Context Protocol) transports.

When you instantiate Computer(host="localhost", port=8000), the SDK establishes a persistent connection to the server and exposes methods like screenshot(), move(x, y), click(), and run_command(). These methods serialize requests and forward them to the server's REST API or MCP endpoint.

Dependencies and Installation

The package is intentionally lightweight. According to libs/python/computer/pyproject.toml, it declares only high-level networking and image dependencies such as pillow, websocket-client, and aiohttp. Optional extras include cua-computer[ui] for Gradio interfaces and cua-computer[lume] for LUMI/LUMIER integrations.

Install the client SDK with:

pip install cua-computer

What Is cua-computer-server?

cua-computer-server is the service component that executes inside the target sandbox, virtual machine, or physical host. It exposes a FastAPI application that listens for incoming client requests and performs the actual low-level OS manipulations using platform-specific automation libraries.

Core Responsibilities and Entry Points

The server launches from computer_server/main.py, which registers HTTP routes, WebSocket handlers, and optional MCP endpoints. Unlike the client package, this service requires heavy OS-control dependencies to manipulate mouse cursors, inject keyboard events, capture screen buffers, and manage window hierarchies.

When running python -m computer_server, the service binds to http://localhost:8000 by default (configurable) and waits for authenticated client connections. Individual command implementations are organized in libs/python/computer-server/computer_server/handlers/, covering mouse, keyboard, and file system operations.

Dependencies and Installation

The server package pulls in substantial dependencies including fastapi, uvicorn, pynput, pywinctl, and playwright. It also defines platform-specific optional groups: [macos], [linux], [windows], and [vnc] for enhanced display support.

Install the server with MCP support using:

pip install "cua-computer-server[mcp]"

The package also exports a console script cua-computer-server defined in libs/python/computer-server/pyproject.toml (lines 62-64), allowing you to run cua-computer-server directly or configure it as a systemd service.

Key Differences Between cua-computer and cua-computer-server

Aspect	cua-computer (Client)	cua-computer-server (Service)
Role	Client library for sending commands	Service that executes OS actions
Primary Entry Point	Computer class in libs/python/computer/computer/computer.py	FastAPI app in computer_server/main.py
Dependencies	Lightweight (pillow, websocket-client, aiohttp)	Heavy OS libraries (fastapi, pynput, pywinctl, playwright)
Installation	pip install cua-computer	pip install cua-computer-server
Target User	AI model developers building automation agents	System administrators maintaining sandbox hosts
Exec Command	Import library in Python	python -m computer_server or cua-computer-server

How to Use Both Packages Together

To build a complete automation pipeline, install both components on their respective machines: the client SDK on your development workstation and the server on the target host.

Step 1: Install the Server

On the machine you want to control (sandbox, VM, or remote host):

# Install with MCP support for model-context-protocol integration

pip install "cua-computer-server[mcp]"

# Start the service

python -m computer_server

# Or use the installed console script

cua-computer-server

The server now listens on port 8000 with HTTP, WebSocket, and MCP endpoints active.

Step 2: Install the Client

On your development machine:

pip install cua-computer

Step 3: Control the Remote Machine

Use the Computer class to connect and automate:

from cua_computer import Computer

# Connect to the server (default: localhost:8000)

computer = Computer(host="localhost", port=8000)

# Capture a screenshot

screenshot = computer.screenshot()
screenshot.save("capture.png")

# Perform mouse actions

computer.move(200, 150)
computer.click()

# Type text

computer.type("Hello, world!")

# Execute shell commands

result = computer.run_command("ls -l /tmp")
print(result.stdout)

Using Model Context Protocol (MCP)

For AI agent integration, connect via MCP transport:

from cua_computer import Computer

# Connect via MCP (requires server started with [mcp] extra)

computer = Computer(host="localhost", port=8000, transport="mcp")

# Access MCP-exposed tools directly

screen_info = computer.tools.computer_get_screen_size()
print(f"Screen dimensions: {screen_info}")

Source Code Structure and Key Files

Understanding the repository layout clarifies which package contains which functionality:

cua-computer (Client SDK):

• libs/python/computer/computer/computer.py – Contains the Computer class and high-level API methods.
• libs/python/computer/pyproject.toml – Defines lightweight dependencies and optional extras for UI and LUME integrations.
• libs/python/computer/README.md – Client installation and usage documentation.

cua-computer-server (Service):

• libs/python/computer-server/computer_server/main.py – FastAPI application with HTTP/WebSocket routing and MCP mounting.
• libs/python/computer-server/computer_server/handlers/ – Low-level command implementations for mouse, keyboard, and file operations.
• libs/python/computer-server/computer_server/mcp_server.py – MCP server integration for AI tool calling.
• libs/python/computer-server/pyproject.toml – Heavy dependency declarations and cua-computer-server console script entry point.

Summary

• cua-computer is the lightweight client SDK that provides a high-level Computer class for sending automation commands.
• cua-computer-server is the heavyweight service that runs inside the target OS to execute mouse, keyboard, screenshot, and shell commands.
• The client connects to the server via HTTP/WebSocket or MCP transport, abstracting network complexity behind simple Python method calls.
• Install the client with pip install cua-computer and the server with pip install cua-computer-server (add [mcp] for Model Context Protocol support).

Frequently Asked Questions

Can I use cua-computer without cua-computer-server?

No. The cua-computer client SDK requires a running instance of cua-computer-server to function. The client sends HTTP requests or MCP messages to the server, which then performs the actual OS actions. Without the server running on the target machine, the client will raise connection errors when attempting to take screenshots or send input commands.

What transport protocols are supported between the client and server?

The architecture supports two primary transport methods: HTTP/WebSocket and Model Context Protocol (MCP). By default, the Computer class uses HTTP REST calls and WebSocket connections for real-time screen sharing. When initializing with transport="mcp", the client communicates via the MCP protocol, enabling integration with AI agents that support the Model Context Protocol standard.

Which package should I install for local development?

Install both packages, but on different machines. Install cua-computer-server on the virtual machine or sandbox you intend to automate, and cua-computer on your development workstation where you write the automation scripts. If you are running both client and server on the same machine for testing, install both packages in separate virtual environments to avoid dependency conflicts, as the server requires platform-specific OS control libraries that the client does not need.

How do I enable MCP support?

Enable MCP by installing the server with the extra dependency group: pip install "cua-computer-server[mcp]". This installs the necessary MCP server libraries. When starting the server, the MCP endpoint becomes available alongside the standard HTTP API. On the client side, instantiate the Computer class with transport="mcp" to route calls through the Model Context Protocol instead of standard HTTP requests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}