computer/docs/content/docs/computer-sdk/computers.mdx

---
title: Cua Computers
description: Understanding Cua computer types and connection methods
---

<Callout>A corresponding <a href="https://github.com/trycua/cua/blob/main/notebooks/computer_nb.ipynb" target="_blank">Jupyter Notebook</a> and <a href="https://github.com/trycua/cua/tree/main/examples/computer-example-ts" target="_blank">NodeJS project</a> are available for this documentation.</Callout>

Before we can automate apps using AI, we need to first connect to a Computer Server to give the AI a safe environment to execute workflows in.

Cua Computers are preconfigured virtual machines running the Computer Server. They can be either macOS, Linux, or Windows. They're found in either a cloud-native container, or on your host desktop.

## Cloud Sandbox

**Easiest & safest way to get started - works on any host OS**

This is a Cloud Sandbox running the Computer Server. Get a container at [trycua.com](https://www.trycua.com/).

<Tabs items={['Python', 'TypeScript']}>
  <Tab value="Python">
    ```python
    from computer import Computer

    computer = Computer(
        os_type="linux",
        provider_type="cloud",
        name="your-sandbox-name",
        api_key="your-api-key"
    )

    await computer.run() # Connect to the sandbox
    ```

  </Tab>
  <Tab value="TypeScript">
    ```typescript
    import { Computer, OSType } from '@trycua/computer';

    const computer = new Computer({
      osType: OSType.LINUX,
      name: "your-sandbox-name",
      apiKey: "your-api-key"
    });

    await computer.run(); // Connect to the sandbox
    ```

  </Tab>
</Tabs>

## Linux on Docker

**Run Linux desktop locally on macOS, Windows, or Linux hosts**

Cua provides two Docker images for running Linux desktops:

<Tabs items={['XFCE (Lightweight)', 'KASM (Full-Featured)']}>
  <Tab value="XFCE (Lightweight)">

    **Recommended for most use cases** - lightweight XFCE desktop with Firefox

    1. Install Docker Desktop or Docker Engine

    2. Pull the CUA XFCE image

    ```bash
    docker pull --platform=linux/amd64 trycua/cua-xfce:latest
    ```

    3. Connect with Computer

    ```python
    from computer import Computer

    computer = Computer(
        os_type="linux",
        provider_type="docker",
        image="trycua/cua-xfce:latest",
        name="my-xfce-container"
    )

    await computer.run() # Launch & connect to Docker sandbox
    ```

  </Tab>
  <Tab value="KASM (Full-Featured)">

    **Full-featured Ubuntu desktop** with additional applications

    1. Install Docker Desktop or Docker Engine

    2. Build or pull the CUA KASM image

    ```bash
    # Option 1: Pull from Docker Hub
    docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest

    # Option 2: Build locally
    cd libs/kasm
    docker build -t cua-ubuntu:latest .
    ```

    3. Connect with Computer

    ```python
    from computer import Computer

    computer = Computer(
        os_type="linux",
        provider_type="docker",
        image="trycua/cua-ubuntu:latest",
        name="my-kasm-container"
    )

    await computer.run() # Launch & connect to Docker sandbox
    ```

  </Tab>
</Tabs>

## Windows Sandbox

**Windows hosts only - requires Windows 10 Pro/Enterprise or Windows 11**

1. Enable Windows Sandbox
2. Install pywinsandbox dependency

```bash
pip install -U git+git://github.com/karkason/pywinsandbox.git
```

3. Connect with Computer

```python
from computer import Computer

computer = Computer(
    os_type="windows",
    provider_type="winsandbox",
    ephemeral=True # Windows Sandbox is always ephemeral
)

await computer.run() # Launch & connect to Windows Sandbox
```

## macOS VM

**macOS hosts only - requires Lume CLI**

1. Install lume cli

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```

2. Start a local Cua macOS VM

```bash
lume run macos-sequoia-cua:latest
```

3. Connect with Computer

```python
from computer import Computer

computer = Computer(
    os_type="macos",
    provider_type="lume",
    name="macos-sequoia-cua:latest"
)

await computer.run() # Launch & connect to the sandbox
```

## Your host desktop

You can also have agents control your desktop directly by running Computer Server without any containerization layer. Beware that AI models may perform risky actions.

```bash
pip install cua-computer-server
python -m computer_server
```

Connect with:

<Tabs items={['Python']}>
  <Tab value="Python">
    ```python

    computer = Computer(use_host_computer_server=True)
    await computer.run() # Connect to the host desktop

    ```

  </Tab>
</Tabs>