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

> Learn the difference between cua-computer client SDK and cua-computer-server. Understand how this client-server architecture enables remote execution and sandbox management.

- Repository: [Cua/cua](https://github.com/trycua/cua)
- Tags: deep-dive
- Published: 2026-04-27

---

**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`](https://github.com/trycua/cua/blob/main/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`](https://github.com/trycua/cua/blob/main/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:

```bash
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`](https://github.com/trycua/cua/blob/main/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:

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

```

The package also exports a console script `cua-computer-server` defined in [`libs/python/computer-server/pyproject.toml`](https://github.com/trycua/cua/blob/main/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`](https://github.com/trycua/cua/blob/main/libs/python/computer/computer/computer.py) | FastAPI app in [`computer_server/main.py`](https://github.com/trycua/cua/blob/main/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):

```bash

# 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:

```bash
pip install cua-computer

```

### Step 3: Control the Remote Machine

Use the `Computer` class to connect and automate:

```python
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:

```python
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`](https://github.com/trycua/cua/blob/main/libs/python/computer/computer/computer.py) – Contains the `Computer` class and high-level API methods.
- [`libs/python/computer/pyproject.toml`](https://github.com/trycua/cua/blob/main/libs/python/computer/pyproject.toml) – Defines lightweight dependencies and optional extras for UI and LUME integrations.
- [`libs/python/computer/README.md`](https://github.com/trycua/cua/blob/main/libs/python/computer/README.md) – Client installation and usage documentation.

**cua-computer-server (Service):**

- [`libs/python/computer-server/computer_server/main.py`](https://github.com/trycua/cua/blob/main/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`](https://github.com/trycua/cua/blob/main/libs/python/computer-server/computer_server/mcp_server.py) – MCP server integration for AI tool calling.
- [`libs/python/computer-server/pyproject.toml`](https://github.com/trycua/cua/blob/main/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.