Cua

커서를 뺏지 않고 배경에서 데스크톱을 조작하는 드라이버

pip install cua

에이전트가 화면을 보고 눌러 작업을 끝내게 만드는 컴퓨터 조작 도구 모음입니다. 드라이버는 맥과 윈도우, 리눅스에서 네이티브 앱을 배경으로 조작해서 사람이 쓰던 커서와 포커스를 빼앗지 않습니다. 같은 CLI 와 MCP 서버를 세 운영체제에서 그대로 쓰고 여러 코딩 도구에서 부릅니다. 샌드박스 쪽은 운영체제와 실행 방식에 상관없이 같은 API 를 제공해서 리눅스 컨테이너든 맥 가상머신이든 윈도우든 안드로이드든 같은 코드로 다룹니다. 모델 학습과 평가, 데이터 생성용 벤치마크가 함께 들어 있습니다.

판단

이럴 때 씁니다

  • 에이전트가 데스크톱 앱을 조작해야 하는데 내 커서는 뺏기기 싫을 때
  • 여러 운영체제에서 같은 코드로 화면 작업을 돌려야 할 때
  • 컴퓨터 조작 모델을 평가하거나 학습 데이터를 만들 때

이럴 땐 쓰지 마세요

  • 웹만 다룬다면 브라우저 자동화가 정확합니다
  • 리눅스의 배경 입력은 창 관리자에 따라 제약이 있습니다
  • 가상머신을 띄우는 경로는 자원을 많이 씁니다

차별점

  • 커서와 포커스를 빼앗지 않고 배경에서 앱을 조작합니다.
  • 같은 CLI 와 MCP 서버를 세 운영체제에서 씁니다.
  • 운영체제와 실행 방식에 상관없이 같은 샌드박스 API 를 제공합니다.
  • 모델 평가와 학습 데이터 생성용 벤치마크가 함께 들어 있습니다.

워크플로

  1. 01드라이버를 설치하고 안내에 따라 권한을 부여합니다.
  2. 02CLI 나 MCP 서버로 앱을 조작해 봅니다.
  3. 03샌드박스가 필요하면 파이썬 패키지를 설치합니다.
  4. 04운영체제에 맞는 이미지를 골라 샌드박스를 띄웁니다.
  5. 05같은 API 로 화면 캡처와 입력, 셸을 다룹니다.

주요 명령

명령설명
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"맥과 리눅스에 드라이버를 설치합니다.
pip install cua샌드박스 SDK 를 설치합니다. 파이썬 3.11 이상이 필요합니다.
Sandbox.ephemeral(Image.linux())운영체제를 바꿔도 같은 API 로 샌드박스를 씁니다.

함정

설치 전에 확인하세요

  • 설치 뒤 별도 권한 부여 안내를 따라야 동작합니다. 특히 맥에서는 접근성 권한이 필요합니다.
  • 리눅스는 창 관리자 방식에 따라 배경 입력에 명시적인 한계가 있다고 문서가 밝히고 있습니다.
  • 저장소가 여러 제품을 담은 구조라 판 태그가 하위 패키지 이름을 달고 나옵니다. 어느 판을 말하는지 확인해야 합니다.
  • 배경 조작이라 화면에 아무 일도 일어나지 않는 것처럼 보입니다. 디버깅할 때 캡처를 함께 봐야 합니다.

비교

컴퓨터 조작 도구는 대체로 화면을 캡처하고 실제 마우스를 움직이는 방식이라 사람이 그 기계를 동시에 쓰지 못합니다. 이쪽은 배경 조작을 앞세워 그 제약을 줄였습니다. 대신 운영체제마다 지원 범위가 다르고 권한 설정이 필요합니다.

최근 변경

최근 판은 의존성 갱신만 담은 유지 보수 배포입니다. 하위 패키지별로 태그가 따로 붙어 나옵니다.

공식 변경 내역