Containerized Ubuntu 22.04 LTS virtual desktop for Computer-Using Agents (CUA). Utilizes QEMU/KVM with Ubuntu Desktop and computer-server pre-installed for remote computer control.

Features

Ubuntu 22.04 LTS Desktop running in QEMU/KVM
Automated installation via cloud-init autoinstall
Pre-installed CUA computer-server for remote computer control
Support for custom OEM scripts during setup
noVNC access for visual desktop interaction

Quick Start

1. Download Ubuntu Server ISO

Download Ubuntu 22.04 LTS Server ISO:

Visit & download the server ISO
After downloading, rename the file to setup.iso
Copy it to the directory src/vm/image/

This ISO is used for automated Ubuntu installation with cloud-init on first run.

2. Build the Image

docker build -t cua-linux:dev .

3. First Run - Create Golden Image

On first run, the container will install Ubuntu from scratch and create a golden image. This takes 15-30 minutes.

# Create storage directory
mkdir -p ./storage

# Run with ubuntu.iso to create golden image
docker run -it --rm \
    --device=/dev/kvm \
    --name cua-linux \
    --mount type=bind,source=/path/to/ubuntu.iso,target=/custom.iso \
    --cap-add NET_ADMIN \
    -v $(pwd)/storage:/storage \
    -p 8006:8006 \
    -p 5000:5000 \
    -e RAM_SIZE=8G \
    -e CPU_CORES=4 \
    -e DISK_SIZE=64G \
    cua-linux:dev

What happens during first run:

Ubuntu 22.04 Server installs automatically using cloud-init autoinstall
Minimal desktop environment is installed with auto-login enabled
OEM setup scripts install Python 3, create venv, and install CUA computer-server
systemd service created for CUA server (runs automatically on login)
X11 access configured for GUI automation
Golden image is saved to /storage directory
Container exits after setup completes

4. Subsequent Runs - Use Golden Image

After the golden image is created, subsequent runs boot much faster (30 sec - 2 min):

# Run without ubuntu.iso - uses existing golden image
docker run -it --rm \
    --device=/dev/kvm \
    --name cua-linux \
    --cap-add NET_ADMIN \
    -v $(pwd)/storage:/storage \
    -p 8006:8006 \
    -p 5000:5000 \
    -e RAM_SIZE=8G \
    -e CPU_CORES=4 \
    cua-linux:dev

Access points:

Computer Server API: http://localhost:5000
noVNC Browser: http://localhost:8006

Container Configuration

Ports

5000: CUA computer-server API endpoint
8006: noVNC web interface for visual desktop access

Environment Variables

RAM_SIZE: RAM allocated to Ubuntu VM (default: "8G", recommended: "8G" for WSL2)
CPU_CORES: CPU cores allocated to VM (default: "8")
DISK_SIZE: VM disk size (default: "64G", minimum: "32G")

Volumes

/storage: Persistent VM storage (golden image, disk)
/custom.iso: Mount point for ubuntu.iso (only needed for first run)
/oem: Optional mount point for custom OEM scripts (built-in scripts included in image)

Architecture

┌─────────────────────────────────────────────────────────┐
│  Docker Container (Linux host)                          │
│                                                         │
│  • Port forwarding: localhost:5000 → EMULATOR_IP:5000   │
│  • Exposes: 5000 (API), 8006 (noVNC)                    │
│                                                         │
│  ┌────────────────────────────────────────────────────┐ │
│  │  QEMU VM (Ubuntu 22.04)                            │ │
│  │                                                    │ │
│  │  • CUA computer-server listens on 5000             │ │
│  │                                                    │ │
│  └────────────────────────────────────────────────────┘ │
│                                                         │
└─────────────────────────────────────────────────────────┘

Communication Flow:

External client → localhost:5000 (host)
Docker port mapping → Container's localhost:5000
Container detects VM IP and waits for server to be ready
CUA computer-server in Ubuntu VM processes request

Development

Modifying Setup Scripts

Setup scripts are in src/vm/setup/:

install.sh: Entry point called after cloud-init installation (runs OEM setup)
setup.sh: Main setup orchestration (copies scripts to /opt/oem)
setup-cua-server.sh: CUA server installation with isolated venv and systemd service

After modifying, rebuild the image:

docker build -t cua-linux:dev .