Cua | 개발자 포트폴리오

Cua

2026.09.20 · 103분

개요

AI 에이전트가 사람처럼 화면을 보고 클릭하고 입력할 수 있도록 "조작 가능한 컴퓨터"와 "그 컴퓨터를 다루는 도구"를 제공하는 오픈소스 컴퓨터 사용(Computer-Use) 인프라입니다. 에이전트와 모델은 사용자가 고르고, Cua는 데스크톱 자동화 드라이버·격리된 샌드박스·로컬 VM·벤치마크를 담당합니다.

30초 요약

항목	내용
무엇인가?	AI 에이전트에게 실제 데스크톱(내 컴퓨터 또는 격리된 VM·컨테이너)과 그 데스크톱을 조작하는 도구를 주는 오픈소스 모노레포
왜 사용하는가?	API가 없는 데스크톱 앱·레거시 시스템·웹 화면을 에이전트가 직접 조작하게 하되, 사용자의 작업을 방해하거나 호스트를 위험에 빠뜨리지 않기 위해
해결하는 문제	스크린샷과 좌표에만 의존하는 불안정한 자동화, 커서·포커스를 빼앗는 자동화, 에이전트를 안전하게 실행할 격리 환경의 부재
주요 사용처	코딩 에이전트의 GUI 작업, 데스크톱 앱 E2E 테스트, 에이전트용 격리 데스크톱, 컴퓨터 사용 에이전트 평가·학습 데이터 수집
핵심 개념	Cua Driver, 접근성 트리 + 스크린샷, `element_token`, 백그라운드 전달, 샌드박스·cua-spacesd, Space, Lume, Cua Bench
Client 사용	O (개발자 PC에서 Cua Driver를 MCP 서버로 붙이거나, Python·TypeScript SDK로 앱 안에 내장)
Server 사용	O (CI·서버에서 로컬 컨테이너·VM 또는 클라우드 샌드박스를 만들고 원격으로 조작)
대표 대안

이 글의 연결 보기

AI 도구

게시 2026.09.20
읽는 데 103분
연결 0개

어떤 라이브러리인가?

AI 에이전트에게 일을 맡기다 보면 결국 "화면"에서 막히는 순간이 옵니다.

사내 정산 프로그램은 API가 없고 데스크톱 앱만 있습니다.
디자인 툴에서 레이어 이름을 바꾸는 작업은 GUI로만 할 수 있습니다.
데스크톱 앱 릴리스 전에 "버튼을 누르면 합계가 바뀌는지"를 매번 사람이 확인합니다.
에이전트가 웹사이트에 로그인해 무언가 하게 하고 싶지만, 내 브라우저를 통째로 맡기기는 불안합니다.

Cua는 이런 상황에서 에이전트에게 "손과 눈"과 "써도 되는 컴퓨터"를 주는 도구 모음입니다. 에이전트가 무엇을 할지는 모델이 판단하고, Cua는 화면을 읽고(관찰) 클릭·입력을 실제로 전달하고(행동) 그 결과를 확인할 수단(검증)을 제공합니다.

기술적으로 정의하면, Cua는 trycua/cua 저장소에 묶인 여러 제품의 모노레포입니다. 2026년 10월 기준 주요 구성은 다음과 같습니다.

구성 요소	역할
Cua Driver	macOS·Windows·Linux의 네이티브 앱과 브라우저를 검사·조작하는 Rust 런타임. CLI, MCP 서버, Python·TypeScript SDK로 연결
Cua SDK와 `cua` CLI	로컬 컨테이너·VM 또는 클라우드에 샌드박스를 만들고 조작하는 Rust 코어 + Python·TypeScript·Swift·Kotlin 바인딩
cua-spacesd	샌드박스 안에서 돌며 프로세스·파일·화면·입력·스트리밍을 제공하는 데몬(포트 3211)
Cua Spaces	에이전트용 데스크톱(Space)을 메뉴 막대에서 보고, 로그인된 앱을 옮겨 넣는(teleport) macOS 앱
Lume	Apple Silicon에서 Apple Virtualization.Framework로 macOS·Linux VM을 만드는 CLI
Cua Bench	컴퓨터 사용 작업을 만들고 에이전트를 채점하며 학습용 trajectory를 내보내는 도구
CUA-S1	폼 입력처럼 좁은 결정을 빠르게 내리는 소형 특화 모델(연구용 초기 릴리스)

이 중 처음 배우는 사람이 가장 먼저 만나고, 다른 구성 요소가 내부적으로 의존하는 것은 Cua Driver입니다. 샌드박스 안의 cua-spacesd도 입력과 접근성 조회를 Cua Driver에 맡깁니다. 그래서 이 문서는 Cua Driver를 중심에 두고, 샌드박스와 평가 도구를 그 위에 쌓는 순서로 설명합니다.

주요 사용 사례

코딩 에이전트의 GUI 작업: Claude Code나 Codex에 Cua Driver를 MCP로 붙여 "계산기에서 6 × 7을 계산해서 결과를 읽어 와"처럼 데스크톱 앱 작업을 시킵니다.
데스크톱 앱 E2E 테스트: 테스트 코드가 Python·TypeScript SDK로 앱을 조작하고, 접근성 트리를 다시 읽어 값이 바뀌었는지 확인합니다.
에이전트용 격리 데스크톱: 에이전트가 내 컴퓨터가 아니라 일회용 Linux·Windows·macOS 샌드박스 안에서 일하게 합니다.
CI에서의 GUI 검증: GitHub Actions에서 샌드박스를 띄우고, 빌드한 바이너리를 주입해 화면 단위로 검사한 뒤 스크린샷을 남깁니다.
에이전트 평가와 데이터 수집: Cua Bench로 작업과 채점 함수를 정의하고 여러 에이전트·모델을 같은 기준으로 비교합니다.

주요 용어는 핵심 개념과 동작 구조에서 자세히 다룹니다.

어떤 문제를 해결하는가?

text

요구사항: 에이전트가 API 없는 데스크톱 앱을 조작하고, 결과가 맞는지 확인하게 하고 싶다
 ↓
일반적인 구현: 스크린샷을 모델에 보여 주고, 모델이 준 좌표로 pyautogui 같은 도구가 클릭한다
 ↓
문제 발생: 좌표가 자주 빗나가고, 실행 중에는 사람이 컴퓨터를 못 쓰며, 성공했는지 확인할 방법이 약하다
 ↓
Cua로 해결: 접근성 트리로 요소를 식별하고, 백그라운드로 전달하고, 행동마다 결과 신호와 재관찰로 검증한다

상황 예시

회계팀이 쓰는 사내 경비 정산 프로그램은 15년 된 데스크톱 앱입니다. 매달 말 담당자가 엑셀의 경비 내역 200건을 이 앱의 입력 폼에 하나씩 옮겨 적습니다. 개발팀은 이 작업을 AI 에이전트에게 맡기려 합니다. 조건은 다음과 같습니다.

앱에는 API도, 가져오기 기능도 없습니다.
담당자는 에이전트가 일하는 동안에도 같은 컴퓨터로 메일을 써야 합니다.
금액이 한 건이라도 잘못 들어가면 안 되므로, 입력 후 화면에 실제로 반영되었는지 확인해야 합니다.

일반적인 구현 방식

가장 먼저 떠올리는 방법은 "스크린샷 → 모델이 좌표 판단 → 좌표 클릭" 루프입니다.

python

# 스크린샷과 좌표에만 의존하는 단순 루프
import pyautogui

def step(model, goal: str) -> bool:
    shot = pyautogui.screenshot()
    action = model.decide(goal, shot)          # 예: {"type": "click", "x": 812, "y": 455}
    if action["type"] == "click":
        pyautogui.click(action["x"], action["y"])  # 실제 마우스가 움직이고 창이 앞으로 온다
    elif action["type"] == "type":
        pyautogui.write(action["text"])            # 포커스가 어디 있든 그 창에 입력된다
    return action["type"] == "done"

이 방식에서 발생하는 문제

좌표가 불안정합니다: 해상도, 창 위치, 화면 배율이 바뀌면 같은 버튼의 좌표가 달라집니다. 모델이 비슷하게 생긴 다른 버튼을 고르기도 합니다.
사람이 컴퓨터를 쓸 수 없습니다: 실제 마우스와 키보드 포커스를 움직이므로, 담당자가 메일을 쓰는 순간 입력이 메일 창으로 들어갈 수 있습니다.
성공 여부를 모릅니다: click()이 예외 없이 끝났다는 것은 "이벤트를 보냈다"는 뜻일 뿐, 입력창에 값이 들어갔다는 뜻이 아닙니다.
호스트가 위험합니다: 에이전트가 잘못 판단하면 사용자의 실제 파일, 로그인된 브라우저 세션을 그대로 건드립니다.
재현과 평가가 어렵습니다: 실패한 실행을 다시 보거나, 다른 모델과 같은 조건으로 비교할 기록이 남지 않습니다.

Cua를 사용하면

같은 요구사항이 다음과 같이 바뀝니다. 설치와 호출 방법은 설치와 첫 사용에서 다룹니다.

에이전트는 get_window_state로 정산 앱 창의 접근성 트리와 스크린샷을 함께 받습니다. "금액" 입력창은 좌표가 아니라 그 스냅샷에서 발급된 element_token으로 가리킵니다.
입력은 기본적으로 백그라운드 전달입니다. 앱이 지원하면 실제 포인터와 포커스를 건드리지 않으므로 담당자는 계속 메일을 쓸 수 있습니다.
모든 행동은 effect(confirmed, unverifiable, refused 등)와 다음 단계 제안(escalation)을 돌려줍니다. 에이전트는 다시 관찰하거나 verify_state로 "금액 칸에 52,000이 보인다"를 확인한 뒤 다음 건으로 넘어갑니다.
위험을 줄이고 싶으면 같은 작업을 일회용 샌드박스 안에서 돌리거나, 허용할 앱과 도구만 적은 매니페스트로 권한을 좁힙니다.

핵심: 화면 자동화를 개발자가 좌표와 sleep으로 버티는 대신, Cua가 접근성 기반 관찰 · 백그라운드 전달 · 행동별 결과 신호 · 격리된 실행 환경으로 나눠서 처리해줍니다.

왜 주목받고 있는가?

trycua/cua는 2025년 1월 공개 이후 GitHub Star 약 2만 8천 개, Fork 약 2천 개를 모았습니다(2026년 10월 기준). 숫자보다 중요한 것은 이런 도구가 왜 필요해졌는가입니다.

에이전트가 코드 밖으로 나가기 시작했습니다. 코딩 에이전트는 파일과 셸은 잘 다루지만, 세상의 많은 업무는 여전히 GUI 안에 있습니다. Cua는 에이전트가 같은 작업 안에서 코드 실행, API 호출, GUI 조작을 오가는 방식을 "Computer-Use 2.0"이라 부르며, 그중 GUI 조작 계층을 담당합니다.

모델이 아니라 실행 계층이 병목이 되었습니다. 컴퓨터 사용이 가능한 모델은 여러 회사에서 나오고 있지만, "어떤 창을 어떻게 조작하고 성공을 어떻게 판정하는가"는 모델 바깥의 문제입니다. Cua는 이 부분을 모델 중립적인 도구(MCP)로 제공하므로 모델을 바꿔도 그대로 씁니다.

운영체제의 접근성 API를 정면으로 씁니다. macOS Accessibility, Windows UI Automation, Linux AT-SPI를 하나의 도구 체계로 감쌌고, 동작마다 "실제 앱 상태가 바뀌었는가"를 테스트 하네스로 검증해 지원 범위를 표로 공개합니다. 되는 것과 안 되는 것을 명확히 거절(refused)로 돌려준다는 점이 신뢰를 줍니다.

로컬 우선으로 방향을 틀었습니다. 2026년 10월 초 대규모 개편으로 Rust 기반 cua SDK가 들어오면서, 샌드박스는 기본적으로 내 컴퓨터에서(컨테이너·QEMU·Lume) 실행되고 클라우드는 옵션이 되었습니다. 비용과 데이터 위치를 직접 통제하고 싶은 팀에게 의미 있는 변화입니다.

개발 속도가 매우 빠릅니다. Driver, SDK, Spaces, Lume이 각각 따로 릴리스되며, 하루에도 여러 번 새 버전이 나옵니다. 활발하다는 뜻이지만 동시에 변화를 따라가야 한다는 뜻이기도 합니다.

다른 컴퓨터 사용 도구와의 항목별 차이는 장단점과 대안 비교에 정리했습니다.

한눈에 정리

항목	내용
라이브러리	Cua (`trycua/cua`, CLI `cua-driver`·`cua`, PyPI `cua-driver`·`cua`·`cua-sandbox`, npm `@trycua/cua-driver`·`@trycua/cua`)
주요 목적	AI 에이전트에게 조작 가능한 컴퓨터와 조작 도구를 제공
해결하는 문제	좌표 기반 자동화의 불안정성, 사용자 작업 방해, 성공 판정 부재, 격리 환경 부재
핵심 개념	Cua Driver, 접근성 트리 + 스크린샷, `element_token`, 백그라운드 전달, action ladder, 샌드박스·cua-spacesd
주요 사용처	에이전트 GUI 작업, 데스크톱 앱 E2E, 격리 데스크톱, 에이전트 평가
Client 활용	개발자 PC에서 MCP로 에이전트에 연결, SDK로 앱에 내장
Server 활용	CI·서버에서 로컬·클라우드 샌드박스 생성, 원격 데스크톱 조작, 벤치마크 실행
장점	의미 단위 조작, 백그라운드 전달, 행동별 결과 신호, 로컬·클라우드 같은 API, 모델 중립
단점	플랫폼별 한계, 권한 설정 부담, 빠른 변화, 구성 요소의 복잡도, 일부 구성의 라이선스 차이
추천 상황	API 없는 데스크톱 앱, 사람과 컴퓨터 공유, 격리 실행, GUI E2E, 에이전트 평가
비추천 상황	웹 전용 작업, API가 있는 작업, 판단이 필요 없는 반복 작업, 캔버스·게임
대표 대안	Anthropic·OpenAI computer use 도구, Playwright·browser-use, E2B Desktop, RPA

Cua 핵심 개념과 동작 구조

Cua Driver, 관찰(접근성 트리 + 스크린샷), element_token, 백그라운드 전달, 권한 모드, 샌드박스·cua-spacesd가 각각 무엇이고 어떻게 맞물려 동작하는지 다룹니다.

용어 한눈에 보기

키워드	설명
Computer-Use 2.0	에이전트가 한 작업 안에서 코드 실행, API 호출, GUI 조작을 오가는 방식. Cua는 이 중 GUI 계층을 담당
Cua Driver	네이티브 앱·브라우저를 관찰하고 조작하는 Rust 런타임. CLI·MCP·SDK로 노출
접근성 트리	운영체제가 장애인 보조 기술용으로 제공하는 UI 구조(역할, 이름, 값, 가능한 동작)
`element_token`	특정 스냅샷에서 발급된 요소 식별자. 다음 스냅샷이 나오면 무효가 됨
백그라운드 전달	실제 포인터·포커스·창 순서를 바꾸지 않고 대상 창에만 입력을 보내는 방식
Action ladder	백그라운드 요소 행동 → 픽셀 → 페이지(DOM) → 포그라운드로 올라가는 단계
권한 모드	`standard`, `bounded`, `unrestricted`. 런타임을 소유한 프로세스가 시작 시 고정
샌드박스	로컬 컨테이너·VM 또는 클라우드에 만드는 격리된 컴퓨터
cua-spacesd	샌드박스 안에서 돌며 셸·파일·화면·입력·스트리밍을 제공하는 데몬(포트 3211)
Space	Cua Spaces 앱과 SDK가 관리하는, 사람과 에이전트가 함께 보는 데스크톱

1. Cua Driver (에이전트의 손과 눈)

쉽게 설명하면

원격 지원 프로그램을 떠올리면 됩니다. 다만 상담원이 사람 대신 AI이고, 화면을 "그림"으로만 보는 것이 아니라 "이 창에는 '저장' 버튼과 '금액' 입력창이 있다"는 목록까지 함께 받는다는 점이 다릅니다.

개발 관점에서는

Cua Driver는 운영체제별 자동화 API를 하나의 도구 체계로 감싼 Rust 런타임입니다.

플랫폼	관찰	입력
macOS	Accessibility API, ScreenCaptureKit	창 단위 CoreGraphics 이벤트, `AXPerformAction`
Windows	UI Automation, Win32	창 메시지, 네이티브 입력
Linux	AT-SPI, X11/Wayland 캡처	AT-SPI 동작, XTest, 포털 입력

같은 런타임을 네 가지 방식으로 쓸 수 있습니다.

연결 방식	쓰는 쪽	형태
MCP 서버	Claude Code, Codex, Cursor 같은 에이전트	`cua-driver mcp` (stdio)
CLI	셸 스크립트, 사람의 디버깅	`cua-driver call <tool> '<json>'` 또는 `cua-driver <tool> '<json>'`
SDK	내 애플리케이션 코드	Python `cua_driver`, TypeScript `@trycua/cua-driver`
데몬	여러 클라이언트가 공유	`cua-driver serve` (macOS는 `CuaDriver.app`이 소유)

중요한 경계가 하나 있습니다. 언어별 SDK는 애플리케이션용이고, 에이전트용이 아닙니다. 에이전트는 이미 MCP 클라이언트를 갖고 있으므로 cua-driver mcp에 바로 붙고, SDK는 테스트 코드나 앱이 Driver를 프로세스 안에 직접 올릴 때 씁니다. 두 SDK 모두 UniFFI로 생성한 바인딩이 같은 Rust 런타임을 호출합니다.

예제

bash

# 실행 중인 앱 목록 (사람이 직접 확인할 때)
cua-driver call list_apps

# 등록된 도구 목록과 특정 도구의 입력 스키마
cua-driver list-tools
cua-driver describe get_window_state

핵심

Cua Driver는 "운영체제 접근성 API를 에이전트가 쓰기 좋은 도구로 바꾼 것"입니다. 에이전트는 MCP로, 내 코드는 SDK로 같은 런타임을 씁니다.

2. 관찰: 접근성 트리 + 스크린샷

쉽게 설명하면

길을 알려 줄 때 사진만 보여 주는 것보다 "사진 + 건물 이름이 적힌 지도"를 함께 주면 훨씬 정확합니다. 스크린샷이 사진이고, 접근성 트리가 지도입니다.

개발 관점에서는

관찰의 기본 단위는 창 하나입니다. get_window_state({pid, window_id})는 그 창의 접근성 트리와 스크린샷을 한 번에 돌려줍니다.

트리는 행동할 수 있는 요소를 역할(button, text field), 이름(label), 값(value), 가능한 동작, 위치와 함께 알려 줍니다. 각 요소에는 element_token이 붙습니다.
스크린샷은 트리에 드러나지 않는 것(캔버스, 아이콘만 있는 버튼)을 보여 주고, 픽셀 좌표 행동의 기준이 됩니다.

창 단위로 잡을 수 없을 때는 get_desktop_state로 주 디스플레이 전체를 캡처합니다. 다만 데스크톱 단위 입력은 항상 포그라운드이므로 더 큰 권한으로 취급됩니다.

예제

bash

# 1) 대상 앱과 창 찾기
cua-driver call list_apps
cua-driver call list_windows '{"pid": 844}'

# 2) 창 하나 관찰. query로 관련 요소만 추리고, 스크린샷은 파일로 저장
cua-driver get_window_state '{"pid":844,"window_id":10725,"query":"금액","screenshot_out_file":"/tmp/run-1/before.png","session":"run-1"}'

응답의 요소 행에는 element_token, role, label, value, actions, frame(화면 좌표), screenshot_frame(같은 응답의 스크린샷 픽셀 좌표)이 들어갑니다. 트리가 너무 크면 max_elements, max_depth로 범위를 제한하는데, 잘렸다고 해서 "요소가 없다"는 증거는 아니라는 점을 기억해야 합니다.

핵심

관찰은 "창 하나의 구조 + 그림"입니다. 의미로 잡을 수 있으면 트리를, 안 되면 같은 응답의 스크린샷을 기준으로 삼습니다.

3. `element_token` (스냅샷에 묶인 요소 이름표)

쉽게 설명하면

번호표와 같습니다. 은행 창구에서 받은 번호표는 그날 그 지점에서만 유효합니다. 새로 번호표를 뽑으면 이전 번호는 쓸 수 없습니다.

개발 관점에서는

element_token은 s0000002a:14처럼 스냅샷 식별자와 요소 위치를 묶은 불투명한 값입니다. 규칙은 단순합니다.

행동은 가장 최근 스냅샷의 토큰으로만 합니다. 토큰을 직접 만들거나 고치지 않습니다.
같은 창을 다시 관찰하면 이전 토큰은 무효가 되고, 응답의 invalidated_snapshot_ids에 표시됩니다. 다른 에이전트가 같은 창을 관찰해도 마찬가지입니다.
오래된 토큰으로 행동하면 stale_element_token 오류가 나며, 다시 관찰하면 됩니다.
예전 방식인 element_index는 행동 도구에서 받지 않습니다.

bash

cua-driver click '{"target":{"kind":"window","pid":844,"window_id":10725},"element_token":"s0000002a:14","session":"run-1"}'

핵심

토큰이 스냅샷에 묶여 있기 때문에 "예전 화면을 보고 지금 화면을 클릭하는" 실수가 구조적으로 막힙니다.

4. 백그라운드 전달과 Action ladder

쉽게 설명하면

옆자리 동료의 키보드를 빼앗아 치는 대신, 동료의 화면 속 특정 창에만 보이지 않는 손을 넣어 버튼을 누르는 것입니다. 그게 안 되는 앱이면 그때 "잠깐 키보드 좀 쓸게요"라고 하고 앞으로 가져옵니다.

개발 관점에서는

창 대상 입력의 기본값은 delivery_mode: "background"입니다. 창을 앞으로 가져오지 않고, 실제 포인터를 움직이지 않고, 포커스를 바꾸지 않습니다. 대신 에이전트 전용 커서 오버레이가 화면에 그려집니다.

백그라운드로 안 되는 경우를 위해 단계가 정해져 있습니다.

요소, 백그라운드: 접근성 동작으로 실행. Driver가 스스로 결과를 확인할 수 있는 유일한 단계
픽셀, 백그라운드: 같은 스크린샷의 x, y 좌표로 전달
페이지: 브라우저 탭이면 CDP로 DOM에 직접 동작
포그라운드: delivery_mode: "foreground"로 창을 앞으로 가져와 실행한 뒤 포커스를 되돌림

각 행동의 응답에는 결과(effect)와 다음 단계 제안(escalation)이 들어 있어서, 에이전트는 응답을 보고 한 단계 올릴지 결정합니다. 자세한 동작은 관찰·행동·검증 루프 깊이 보기에서 다룹니다.

핵심

기본은 "사용자를 방해하지 않는 경로"이고, 더 침범적인 경로는 결과를 보고 한 단계씩, 허락된 범위 안에서만 올라갑니다.

5. 권한 모드 (무엇까지 허용할 것인가)

쉽게 설명하면

건물 출입증의 등급과 같습니다. 일반 출입증(standard), 특정 층만 열리는 출입증(bounded), 마스터키(unrestricted)가 있고, 출입증은 입장할 때 한 번 정해지면 안에서 바꿀 수 없습니다.

개발 관점에서는

모드	용도	동작
`standard`	로컬 CLI·MCP 기본값	관찰, 입력, 격리 브라우저, 녹화, 검증된 파일 전송을 프롬프트 없이 허용. 로그인된 브라우저 프로필 연결은 별도 허가 필요
`bounded`	무인 에이전트, 내장 앱	검토된 매니페스트에 적힌 도구·앱·파일만 허용하고 나머지는 거부
`unrestricted`	일회용·완전 신뢰 환경	승인 검사를 건너뜀. `--dangerously-bypass-approvals` 필요

모드는 런타임을 소유한 프로세스가 시작할 때 고정합니다. cua-driver serve는 플래그로, cua-driver mcp나 내장 호스트는 CUA_DRIVER_PERMISSION_MODE 같은 환경 변수로 정합니다. MCP 서버를 에이전트에 등록하는 것만으로는 모드가 정해지지 않는다는 점이 자주 헷갈립니다.

예제

yaml

# bounded 모드 매니페스트: 정산 앱 하나와 입력 폴더 하나만 허용
version: 3
expires_after: 8h
idle_timeout: 30m

allow:
  tools:
    - start_session
    - end_session
    - list_windows
    - get_window_state
    - click
    - type_text
    - verify_state

resources:
  apps:
    - executable: /opt/expense-desk/expense-desk   # macOS는 bundle_id 사용
      launch: true
      windows: all
      terminate: driver_launched
  files:
    read:
      - dir: /data/expenses
        recursive: true

bash

export CUA_DRIVER_PERMISSION_MODE=bounded
export CUA_DRIVER_CAPABILITY_MANIFEST_FILE=/etc/cua/expense-agent.yaml
export CUA_DRIVER_CAPABILITY_MANIFEST_APPROVED=1

핵심

권한은 에이전트에게 묻는 것이 아니라 런타임을 띄울 때 정합니다. 무인으로 돌릴수록 bounded로 좁힙니다.

6. 샌드박스와 cua-spacesd (써도 되는 컴퓨터)

쉽게 설명하면

신입 사원에게 실제 운영 서버 대신 연습용 PC를 한 대 주는 것입니다. 망가져도 지우고 새로 받으면 됩니다.

개발 관점에서는

Cua SDK(cua, cua-sandbox)는 어떤 OCI 이미지든 샌드박스로 띄웁니다. 생성할 때 세 가지를 고릅니다.

축	값	기본값
어디서 (`on`)	`local`, `cloud`, `direct:<주소>`	`local`
종류 (`kind`)	`container`, `vm`, `auto`	`auto` (이미지에 따라)
엔진 (`runtime`)	로컬: `gvisor`, `runc`, `qemu`, `lume` / 클라우드: `gvisor`, `kubevirt`	`auto`

샌드박스는 내부에 에이전트가 없어도 만들어지고 지워집니다. 대신 cua-spacesd가 들어 있는 이미지(공식 ghcr.io/trycua/linux:24.04 등)라면 셸, 파일, 스크린샷, 입력, 창·접근성 조회, 화면 스트리밍을 추가로 쓸 수 있습니다. cua-spacesd는 입력과 접근성을 샌드박스 안의 Cua Driver에 맡깁니다. 즉 샌드박스 = 격리된 컴퓨터, Cua Driver = 그 안에서 실제로 조작하는 손입니다.

예제

python

import asyncio
from cua_sandbox import Image, Sandbox

async def main():
    # 내 컴퓨터에 일회용 Linux 데스크톱을 띄우고, 블록이 끝나면 삭제
    async with Sandbox.ephemeral(Image.linux()) as sb:
        print((await sb.shell.run("uname -a")).stdout)
        open("desktop.png", "wb").write(await sb.screenshot())

asyncio.run(main())

핵심

에이전트를 내 컴퓨터에서 돌릴지(Cua Driver 직접), 격리된 컴퓨터에서 돌릴지(샌드박스 + 안의 Cua Driver)는 위험도와 작업 성격으로 고릅니다.

7. 주변 구성 요소: Spaces, Lume, Cua Bench, CUA-S1

Cua Spaces: 샌드박스나 내 다른 기계를 "Space"로 등록해 메뉴 막대에서 보고, 사람과 에이전트가 각자 커서를 갖고 같은 데스크톱에서 일하게 하는 macOS 앱입니다. 로그인된 Chrome·Slack 세션을 승인 후 Space로 옮기는 teleport 기능이 있습니다. 앱은 MIT가 아니라 FSL-1.1-MIT 라이선스입니다.
Lume: Apple Silicon Mac에서 macOS·Linux VM을 만드는 CLI입니다. 로컬 macOS 샌드박스의 기반이 됩니다.
Cua Bench: 작업(setup, 오라클 solve, evaluate)을 Python으로 정의하고, 같은 채점 함수로 오라클·사람·에이전트를 평가합니다. OSWorld-Verified, MiniWoB++ 같은 기존 벤치마크 어댑터도 있습니다.
CUA-S1: "이 입력칸에 어떤 값이 들어가야 하는가" 같은 좁은 결정을 빠르게 점수화하는 소형 모델군입니다. 첫 프로필은 폼 입력이며, 소스만 공개된 초기 연구 릴리스입니다.

8. 전체 동작 구조

Cua는 에이전트와 운영체제 사이에서 "관찰과 전달"을 담당하는 계층입니다.

mermaid

flowchart LR
    U[사용자] -->|작업 지시| A[에이전트<br/>Claude Code · Codex · 내 코드]
    A <-->|추론| LLM[모델<br/>어떤 제공사든]

    A -->|MCP · CLI · SDK| D

    subgraph Host[내 컴퓨터]
        D[Cua Driver<br/>권한 모드 · 세션]
        OS[OS 접근성 API<br/>AX · UIA · AT-SPI]
        APP[네이티브 앱 · 브라우저]
        D <--> OS
        OS <--> APP
    end

    A -->|cua SDK| SB

    subgraph SB[샌드박스 · 로컬 또는 클라우드]
        SP[cua-spacesd :3211]
        D2[Cua Driver]
        APP2[샌드박스 안의 앱]
        SP --> D2
        D2 <--> APP2
    end

한 번의 작업이 처리되는 순서는 다음과 같습니다.

시작점: 사용자가 에이전트에게 "정산 앱에 이번 달 경비를 입력해"처럼 지시합니다. 에이전트는 MCP 도구 목록에서 Cua Driver의 도구들을 봅니다.
Cua가 개입하는 시점: 에이전트가 list_apps, list_windows로 대상 창을 정하고 get_window_state를 호출하는 순간부터입니다. Driver는 권한 모드와 매니페스트를 확인한 뒤 창의 트리와 스크린샷을 돌려줍니다.
내부 처리: 에이전트(모델)가 트리에서 "금액" 입력창의 element_token을 고르고 type_text를 호출합니다. Driver는 백그라운드 접근성 경로로 값을 넣고, 결과를 effect와 escalation으로 보고합니다.
외부 시스템과의 연결: 실제 입력은 운영체제 접근성 API를 통해 앱에 전달됩니다. 샌드박스를 쓰는 경우에는 cua SDK → cua-spacesd(gRPC) → 샌드박스 안의 Cua Driver 순서로 같은 일이 일어납니다.
결과 반환: 에이전트는 verify_state나 새 스냅샷으로 값이 반영됐는지 확인하고, 확인된 경우에만 다음 건으로 넘어갑니다. 요청하면 start_recording으로 행동마다 전후 스크린샷이 남는 trajectory를 기록할 수 있습니다.

행동 하나를 상태 흐름으로 보면 다음과 같습니다.

mermaid

stateDiagram-v2
    [*] --> Observe: get_window_state
    Observe --> Act: element_token 선택
    Act --> Verify: effect confirmed 또는 unverifiable
    Act --> Escalate: refused 또는 suspected_noop
    Escalate --> Observe: 다음 단계 경로로 재관찰
    Verify --> Observe: 조건 불만족, 재관찰
    Verify --> [*]: 조건 만족

Cua 설치와 첫 사용

무엇을 설치할지 고르는 기준, Cua Driver와 Cua SDK의 설치·권한 설정, 에이전트 연결, 가장 간단한 첫 실행, 설치할 때 자주 겪는 문제를 다룹니다.

무엇을 설치할지 먼저 고르기

Cua는 제품이 여러 개라서 "전부 설치"보다 목적에 맞는 하나부터 시작하는 것이 좋습니다.

하고 싶은 일	설치할 것
내 컴퓨터의 앱을 에이전트가 조작	Cua Driver (`cua-driver`)
내 코드에서 데스크톱 앱 조작·검증	Cua Driver + Python `cua-driver` 또는 npm `@trycua/cua-driver`
격리된 샌드박스에서 에이전트 실행	`cua` CLI + Python `cua-sandbox` (또는 `@trycua/cua`)
에이전트용 데스크톱을 앱으로 관리	Cua Spaces (macOS 26 이상)
에이전트 평가	`cua-bench` (+ 로컬 샌드박스 실행용 `cua` CLI)

이 문서는 가장 많이 쓰는 Cua Driver와 샌드박스 SDK를 다룹니다.

설치 1. Cua Driver

필요 조건은 macOS 14 이상, Windows 10/11, 또는 X11·XWayland와 AT-SPI 2가 있는 x86_64 Linux 데스크톱입니다. 관리자 권한은 필요 없습니다.

macOS

bash

/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

# 앱 번들로 데몬을 시작해야 macOS가 권한 주체를 CuaDriver로 인식한다
open -n -g -a CuaDriver --args serve

# 손쉬운 사용(Accessibility)과 화면 및 시스템 오디오 녹음 권한 요청
cua-driver permissions grant

설치 스크립트는 CuaDriver.app을 /Applications에 두고 ~/.local/bin/cua-driver 링크를 만듭니다. 시스템 설정에서 두 권한 모두 CuaDriver를 켜야 합니다. 화면 기록 권한이 없으면 관찰 결과에 스크린샷 없이 트리만 들어옵니다.

Windows (PowerShell)

powershell

irm https://cua.ai/driver/install.ps1 | iex
cua-driver autostart kick

SSH 세션이 아니라 실제 데스크톱 세션에서 실행해야 합니다. 데몬이 사용자 세션 안에 있어야 데스크톱에 접근할 수 있습니다.

Linux

bash

sudo apt install libxi6 at-spi2-core   # 최소 이미지에서만 필요
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
cua-driver serve                        # 데스크톱 세션 안의 터미널에서 실행하고 열어 둔다

데몬이 조작할 앱과 같은 디스플레이·접근성 버스를 써야 하므로, SSH가 아니라 데스크톱 세션의 터미널에서 띄웁니다. GNOME에서는 함께 설치되는 WinRects Shell 헬퍼를 설치하고 한 번 로그아웃해야 합니다.

설치 확인

bash

cua-driver --version
cua-driver status
cua-driver doctor
cua-driver permissions status   # macOS 전용
cua-driver call list_apps       # 지금 열려 있는 GUI 앱이 보여야 정상

list_apps가 빈 목록이면 데몬이 데스크톱을 보지 못하는 상태입니다. doctor 결과부터 확인합니다.

설치 2. 에이전트에 연결

Claude Code

bash

claude mcp add --transport stdio cua-driver -- cua-driver mcp
cua-driver skills install    # 에이전트가 Driver를 언제·어떻게 쓰는지 알려 주는 Skill 설치

Codex, Cursor 등

bash

cua-driver mcp-config --client codex    # 해당 클라이언트용 등록 명령·설정을 출력
cua-driver mcp-config --client cursor   # ~/.cursor/mcp.json 에 붙여 넣을 내용
cua-driver skills install
cua-driver skills status

표준 MCP 설정 형식을 받는 클라이언트라면 다음 내용으로 충분합니다.

json

{
  "mcpServers": {
    "cua-driver": { "command": "cua-driver", "args": ["mcp"] }
  }
}

등록한 뒤에는 에이전트 클라이언트를 다시 시작해야 도구 목록이 갱신됩니다.

설치 3. 샌드박스용 `cua` CLI와 SDK

bash

# cua CLI 설치. --only 로 체크리스트 없이 필요한 것만 고를 수 있다
curl -fsSL https://cua.ai/install.sh | sh

# 로컬 런타임(Docker·Podman, gVisor, QEMU, Lume) 상태 확인과 준비
cua runtime doctor
cua runtime setup

bash

# Python 3.11 이상 3.14 미만
pip install cua-sandbox

bash

# TypeScript
npm install @trycua/cua

로컬 컨테이너 샌드박스에는 Docker, Podman, Colima 중 하나가 필요합니다. 클라우드 샌드박스를 쓰려면 cua auth login으로 로그인하거나 CUA_CLIENT_ID, CUA_CLIENT_SECRET을 설정합니다.

가장 간단한 예제

에이전트로 계산기 조작하기

Cua Driver 공식 시작 예제는 "계산기에서 6 × 7을 계산하고 42를 읽어 오기"입니다. 에이전트 세션을 새로 열고 다음과 같이 요청합니다.

text

Using Cua Driver, open the installed calculator app, compute 6 × 7,
and read the displayed result back from a fresh snapshot.

무엇을 생성하는가: 에이전트가 Driver 세션을 하나 열고, 필요하면 launch_app으로 계산기를 백그라운드에서 실행합니다.
어떤 값을 전달하는가: list_windows로 고른 정확한 pid와 window_id, 그리고 get_window_state가 돌려준 버튼들의 element_token을 click에 넘깁니다.
Cua가 무엇을 처리하는가: 백그라운드 접근성 경로로 6, ×, 7, = 버튼을 누릅니다. 사용자의 포인터는 그대로이고, 화면에서 움직이는 커서는 에이전트용 오버레이입니다.
어떤 결과를 반환하는가: 에이전트가 새 스냅샷에서 결과 표시 요소의 값 42를 읽어 보고합니다. "클릭이 성공했다"가 아니라 "화면에 42가 보인다"가 완료 조건입니다.

코드로 샌드박스 하나 띄우기

python

import asyncio
from cua_sandbox import Image, Sandbox, http

async def main():
    # 공식 Python 이미지에서 웹 서버를 띄우고, 준비되면 호출한다
    async with Sandbox.ephemeral(
        Image.from_registry("python:3.12-slim"),
        command=["python", "-m", "http.server", "8000"],
        services={"web": 8000},
        wait_for=http("web", "/"),
    ) as sb:
        print((await sb.service("web").request("GET", "/")).status_code)  # 200
        print(await sb.service("web").url())                              # 내 컴퓨터에서 쓸 수 있는 URL

asyncio.run(main())

같은 일을 CLI로 하면 다음과 같습니다.

bash

cua sb create python:3.12-slim --name web --service web=8000 --wait http:web/ \
  -- python -m http.server 8000
cua sb url web web
cua sb rm web -f

Sandbox.ephemeral은 블록이 끝나면 샌드박스를 지우지만, CLI로 만든 샌드박스는 cua sb rm으로 지울 때까지 남습니다. 처음 쓰는 이미지는 내려받는 데 몇 분이 걸릴 수 있습니다.

설치할 때 주의할 점

macOS에서는 반드시 앱 번들로 데몬을 띄웁니다. 권한은 실행 파일 경로가 아니라 앱 identity(com.trycua.driver)에 부여됩니다. 터미널에서 raw cua-driver serve를 직접 실행하는 구성은 지원되지 않고, 임의의 바이너리 경로에 권한을 주면 안 됩니다.
권한을 켰는데 false로 나오면 예전 번들 ID(com.trycua.cuadriver 등)에 남은 권한일 수 있습니다. 모든 MCP 클라이언트를 끄고 cua-driver stop 후 tccutil reset Accessibility com.trycua.driver처럼 Cua Driver 항목만 초기화한 뒤 다시 부여합니다. 전체 초기화나 TCC.db 직접 수정은 하지 않습니다.
MCP 등록은 권한 모드를 정하지 않습니다. macOS에서는 CuaDriver.app 데몬이, Windows·Linux에서는 클라이언트 설정의 env에 넣은 CUA_DRIVER_PERMISSION_MODE가 모드를 정합니다.
GitHub 릴리스의 "Pre-release" 표시는 불안정 버전이라는 뜻이 아닙니다. 모노레포에서 제품별 "Latest"가 서로 뒤바뀌지 않도록 붙인 표시이고, cua-driver-rs-v0.33.3 같은 일반 SemVer는 안정 릴리스입니다. 반대로 nightly- 태그는 실제 불안정 채널입니다.
설치 스크립트를 파이프로 바로 실행하는 것이 부담스럽다면 릴리스 자산의 버전 고정 설치 스크립트와 SHA256 체크섬을 확인한 뒤 실행합니다.
cua-sandbox[driver] extra는 특정 cua-driver 버전을 고정합니다. 내 컴퓨터에 설치한 Driver와 버전이 다를 수 있으므로, 샌드박스 안 Driver를 타입 있는 SDK로 다룰 때는 설치된 버전의 API를 확인합니다.

Cua 활용 예시 ① 내 컴퓨터의 앱을 에이전트에게 맡기기

Claude Code에 Cua Driver를 붙여 API 없는 데스크톱 앱에 데이터를 입력하고 검증하는 과정과, 같은 작업을 사람 없이 돌릴 때 권한을 좁혀 실행하는 방법을 다룹니다.

예제 1. 경비 내역을 데스크톱 정산 앱에 입력하기

요구사항

~/expenses/2026-09.csv에 있는 경비 내역을 사내 정산 앱 "Expense Desk"의 입력 폼에 한 건씩 등록한다. 각 건은 날짜·거래처·금액·계정과목 네 칸이다. 저장 후 목록 화면에 그 건이 실제로 나타났는지 확인하고, 확인되지 않은 건은 건너뛰지 말고 보고한다. 담당자는 그동안 같은 Mac에서 다른 일을 한다.

구현

설치와 첫 사용에서 Claude Code에 Cua Driver를 등록하고 Skill을 설치했다고 가정합니다. 작업 지시는 "무엇을"과 "어떻게 확인할지"를 함께 적습니다.

text

Cua Driver로 Expense Desk 앱을 조작해줘.

1. ~/expenses/2026-09.csv 를 읽어 각 행을 입력한다.
2. 행마다: 새 항목 폼을 열고 날짜, 거래처, 금액, 계정과목을 입력한 뒤 저장한다.
3. 저장 후 목록 창의 새 스냅샷에서 해당 거래처와 금액이 보이는지 verify_state로 확인한다.
4. 확인이 unsatisfied 또는 unknown이면 같은 행을 다시 입력하지 말고, 그 행 번호와 이유를 기록한 뒤 다음 행으로 넘어간다.
5. 백그라운드로만 조작하고, 포그라운드가 필요하면 멈추고 나에게 물어본다.
6. 작업 전체를 ~/cua-runs/2026-09 에 녹화한다.

에이전트는 Skill의 절차에 따라 다음과 같은 도구 호출을 이어 갑니다. 아래는 그중 한 건을 CLI 형태로 옮긴 것입니다(실제 ID와 토큰은 매번 응답에서 받은 값을 씁니다).

bash

# 녹화 시작 (요청했을 때만)
cua-driver start_recording '{"output_dir":"~/cua-runs/2026-09","record_video":false}'

# 대상 앱과 창 확정: 첫 번째 항목을 무작정 고르지 않고 제목으로 고른다
cua-driver list_apps '{}'
cua-driver list_windows '{"pid":5120}'

# 입력 폼 관찰: 필요한 요소만 query로 추린다
cua-driver get_window_state '{"pid":5120,"window_id":88,"query":"금액","session":"exp-0901"}'

# 같은 스냅샷의 토큰으로 입력 (백그라운드가 기본값)
cua-driver type_text '{"target":{"kind":"window","pid":5120,"window_id":88},"element_token":"s00000031:7","text":"52000","session":"exp-0901"}'

# 저장 버튼 클릭
cua-driver click '{"target":{"kind":"window","pid":5120,"window_id":88},"element_token":"s00000031:12","session":"exp-0901"}'

# 목록 창에서 결과 확인
cua-driver verify_state '{"pid":5120,"window_id":87,"expect":[{"element":{"selector":{"label_contains":"52,000"},"exists":true}}],"session":"exp-0901"}'

실행 흐름

text

사용자: 작업 지시
 ↓
에이전트: CSV 읽기 (파일 도구, GUI 아님)
 ↓
Cua Driver: list_apps / list_windows로 Expense Desk의 정확한 pid, window_id 확정
 ↓
반복 (행마다)
  get_window_state → element_token 선택
  → type_text / click (background)
  → 응답의 effect 확인 (confirmed / unverifiable / refused)
  → verify_state로 목록 창에 반영됐는지 확인
  → satisfied면 다음 행, 아니면 기록 후 다음 행
 ↓
stop_recording → 결과 요약 보고

코드 설명

CSV는 GUI로 열지 않습니다. 파일 읽기는 에이전트의 파일 도구로 처리합니다. Cua 문서도 GUI 밖에서 끝낼 수 있는 일은 API·파일·CLI로 하라고 권합니다. GUI는 꼭 필요한 입력 단계에만 씁니다.
대상을 매 행동마다 정확히 지정합니다. target에 pid와 window_id를 함께 넣습니다. 세션(session)은 수명 관리용 이름표일 뿐, 어느 창을 조작할지 정해 주지 않습니다.
토큰은 방금 본 스냅샷의 것만 씁니다. 저장 후 폼이 다시 그려지면 이전 토큰은 무효가 되므로 다음 행에서는 다시 관찰합니다.
effect와 작업 성공은 다릅니다. type_text가 confirmed를 돌려줘도 그것은 "값이 입력창에 들어갔다"까지입니다. "저장되어 목록에 나타났다"는 verify_state로 따로 확인합니다.
다시 입력하지 않는 규칙이 중요합니다. 결과가 불확실한 상태에서 같은 행을 재입력하면 중복 경비가 생깁니다. Cua Skill 규칙도 "부분 실행·취소·결과 불명 행동을 자동으로 재생하지 말라"고 정합니다.

왜 이렇게 사용하는가?

이 작업의 위험은 "입력이 빗나가는 것"보다 "잘못 입력됐는데 성공했다고 믿는 것"입니다. 좌표 클릭 자동화는 이 둘을 구분할 수단이 없습니다. Cua를 쓰면 요소를 의미로 지정하고, 행동마다 결과 신호를 받고, 검증 도구로 앱의 실제 상태를 확인하는 세 겹의 장치가 생깁니다. 백그라운드 전달 덕분에 담당자는 그동안 같은 Mac에서 계속 일할 수 있고, 녹화된 trajectory로 나중에 문제 건을 재확인할 수 있습니다.

예제 2. 같은 작업을 사람 없이 돌리기

요구사항

매달 1일 새벽에 같은 입력 작업을 자동으로 실행한다. 사람이 지켜보지 않으므로 에이전트가 정산 앱 이외의 앱을 건드리거나, 입력 폴더 밖의 파일을 읽을 수 없어야 한다.

구현

에이전트는 Claude Agent SDK로 띄우고, Cua Driver는 bounded 모드로 실행합니다. Windows·Linux에서는 MCP 서버 설정의 env로 권한 모드를 넘깁니다. macOS에서는 MCP 프로세스가 CuaDriver.app 데몬을 거치므로, 데몬을 같은 모드로 띄워 두어야 합니다.

yaml

# /etc/cua/expense-agent.yaml
version: 3
expires_after: 2h
idle_timeout: 15m

allow:
  tools:
    - start_session
    - end_session
    - list_apps
    - list_windows
    - launch_app
    - get_window_state
    - click
    - type_text
    - verify_state

resources:
  apps:
    - executable: /opt/expense-desk/expense-desk
      launch: true
      windows: all
      terminate: driver_launched
  files:
    read:
      - dir: /data/expenses
        recursive: true

python

# run_monthly.py  (pip install claude-agent-sdk)
import anyio
from claude_agent_sdk import ClaudeAgentOptions, query

CUA_TOOLS = [
    "list_apps", "list_windows", "launch_app", "get_window_state",
    "click", "type_text", "verify_state", "start_session", "end_session",
]

options = ClaudeAgentOptions(
    mcp_servers={
        "cua-driver": {
            "type": "stdio",
            "command": "/home/ops/.local/bin/cua-driver",  # command -v cua-driver 로 확인한 절대 경로
            "args": ["mcp"],
            "env": {
                "CUA_DRIVER_PERMISSION_MODE": "bounded",
                "CUA_DRIVER_CAPABILITY_MANIFEST_FILE": "/etc/cua/expense-agent.yaml",
                "CUA_DRIVER_CAPABILITY_MANIFEST_APPROVED": "1",
            },
        }
    },
    # 에이전트가 쓸 수 있는 도구를 Cua 도구와 파일 읽기로 제한한다
    allowed_tools=[f"mcp__cua-driver__{name}" for name in CUA_TOOLS] + ["Read"],
)

PROMPT = """/data/expenses/2026-09.csv 의 각 행을 Expense Desk에 입력하라.
행마다 저장 후 verify_state로 목록 반영을 확인하고, 확인되지 않은 행은 재입력하지 말고 보고하라.
포그라운드 전달이 필요하면 그 행을 건너뛰고 보고하라."""

async def main():
    async for message in query(prompt=PROMPT, options=options):
        print(message)

anyio.run(main)

왜 이렇게 사용하는가?

사람이 보고 있을 때는 이상한 행동을 바로 멈출 수 있지만, 무인 실행에서는 그럴 수 없습니다. 그래서 통제 지점을 두 곳에 둡니다.

에이전트 쪽(allowed_tools): 모델이 셸이나 쓰기 도구를 호출하지 못하게 합니다.
Driver 쪽(bounded 매니페스트): 설령 에이전트 설정이 바뀌어도, Driver 자체가 매니페스트에 없는 앱·도구·파일을 거부합니다. 매니페스트는 기본 거부(deny-by-default)이고 만료 시간도 있습니다.

프롬프트로 "다른 앱은 건드리지 마"라고 쓰는 것은 부탁이지만, 매니페스트는 실행 계층의 강제입니다. 두 장치를 함께 두는 것이 무인 에이전트의 기본 형태입니다.

함께 알아 두면 좋은 기능

Claude Code 호환 모드: Claude Code의 이미지 기반 컴퓨터 사용 흐름이 Driver의 창 스크린샷을 쓰게 하려면 cua-driver mcp --claude-code-computer-use-compat으로 등록합니다. 이때 screenshot 도구는 pid와 window_id를 요구하고 그 창만 캡처합니다.
로그인된 브라우저 프로필: 기본은 격리된 브라우저입니다. 이미 로그인된 Chrome·Edge 프로필에 붙이려면 cua-driver mcp --grant existing-profile처럼 명시적으로 허가해야 합니다.
녹화와 렌더링: start_recording/stop_recording으로 남긴 기록은 cua-driver recording render <dir> <out.mp4>로 클릭 지점을 확대하는 데모 영상으로 바꿀 수 있습니다.

Cua 활용 예시 ② 애플리케이션 코드에서 샌드박스 다루기

에이전트가 아니라 내가 작성하는 코드가 Cua를 쓰는 경우를 다룹니다. Driver SDK로 데스크톱 앱을 조작·검증하는 방법, 샌드박스를 만들어 화면을 조작하고 사람에게 보여 주는 방법, 샌드박스 안에서 코딩 에이전트를 돌리는 방법을 차례로 봅니다.

Cua에는 "Client/Server" 구분보다 "에이전트가 쓰는가, 내 코드가 쓰는가" 구분이 더 잘 맞습니다. 활용 예시 ①이 에이전트가 MCP로 쓰는 경우였다면, 이 문서는 애플리케이션 코드가 SDK로 쓰는 경우입니다.

활용할 수 있는 기능

기능	패키지	용도
Driver SDK (in-process)	Python `cua-driver`, npm `@trycua/cua-driver`	내 프로세스 안에서 Driver 런타임을 올려 앱을 타입 있는 API로 조작
샌드박스 생명주기	Python `cua-sandbox`, npm `@trycua/cua`	컨테이너·VM 샌드박스 생성, 서비스 포트, 공개 URL, 삭제
샌드박스 데스크톱 제어	같은 패키지 (cua-spacesd 필요)	스크린샷, 마우스, 키보드, 셸, 파일, 터미널
브라우저 뷰어	`sb.viewer_url()`, `cua sb view`	샌드박스 화면을 사람에게 HTML5 스트림으로 보여 주기
에이전트용 MCP	`cua mcp --sandbox NAME`	코딩 에이전트에게 샌드박스 하나를 도구로 넘기기
샌드박스 안 코딩 에이전트	`sb.agents()` (cua SDK)	Claude Code·Codex 등을 샌드박스 안에서 실행하고 이벤트 수신

실제 예제 1. Driver SDK로 데스크톱 앱 동작 검증하기

사내 데스크톱 앱 "Window Demo"의 Counter 창에서 Increment 버튼을 누르면 Count 값이 바뀌는지 확인하는 테스트입니다. 실제 마우스를 움직이지 않으므로 개발자가 작업 중인 Mac에서도 돌릴 수 있습니다.

python

# check_counter.py  (pip install cua-driver)
import asyncio

from cua_driver import (
    ActionTarget, ClickButton, ClickInput, ClickPosition, CuaDriver,
    GetWindowStateInput, InputDeliveryMode, ListAppsInput, ListWindowsInput,
)


def unique(items, what):
    # 후보가 정확히 하나가 아니면 멈춘다: "첫 번째 것"을 고르는 습관이 오조작의 원인
    if len(items) != 1:
        raise RuntimeError(f"Expected one {what}, found {len(items)}")
    return items[0]


async def main() -> None:
    driver = CuaDriver.create()  # 데몬 없이 이 프로세스 안에 런타임을 올린다
    try:
        apps = await driver.list_apps(ListAppsInput())
        app = unique([a for a in apps.apps if a.name == "Window Demo" and a.running], "app")
        windows = await driver.list_windows(ListWindowsInput(pid=app.pid, on_screen_only=True))
        window = unique([w for w in windows.windows if w.title == "Counter"], "window")

        capture = GetWindowStateInput(
            pid=app.pid, window_id=window.window_id, session=None, query=None,
            include_accessibility_tree=True, include_screenshot=True,
            screenshot_out_file=None, max_elements=None, max_depth=None, max_dimension=None,
        )

        async def snapshot():
            state = await driver.get_window_state(capture)
            if state.degraded or state.truncated:
                raise RuntimeError("Snapshot is degraded or truncated")
            return state

        before = await snapshot()
        button = unique([e for e in before.elements or [] if e.label == "Increment"], "button")
        count = unique([e for e in before.elements or [] if e.label == "Count"], "counter")

        await driver.click(ClickInput(
            target=ActionTarget.WINDOW(pid=app.pid, window_id=window.window_id),
            position=ClickPosition.ELEMENT(element_token=button.element_token),
            delivery_mode=InputDeliveryMode.BACKGROUND,  # 실패해도 포그라운드로 자동 재시도하지 않는다
            session=None, button=ClickButton.LEFT, count=1,
        ))

        after = await snapshot()  # 클릭이 반환됐다는 것은 증거가 아니다. 두 번째 스냅샷이 증거다
        updated = unique([e for e in after.elements or [] if e.label == "Count"], "counter")
        if updated.value == count.value:
            raise RuntimeError("Click returned, but the counter did not change")
        print("Verified:", count.value, "->", updated.value)
    finally:
        await driver.shutdown()


asyncio.run(main())

코드 설명

CuaDriver.create()는 Driver 런타임을 현재 프로세스에 직접 올립니다. 별도 데몬이나 MCP 서버가 필요 없습니다(macOS에서는 이 프로세스를 띄운 앱의 권한을 따릅니다).
unique()로 앱·창·요소가 정확히 하나인지 확인합니다. 같은 이름의 창이 두 개일 때 아무거나 고르면 엉뚱한 창을 조작합니다.
degraded나 truncated 스냅샷은 신뢰하지 않습니다. 트리가 잘렸다면 찾는 요소가 "없는" 것이 아니라 "안 보인" 것일 수 있습니다.
클릭 뒤 다시 관찰해서 값이 바뀌었는지 비교합니다. 이것이 Cua가 권하는 관찰 → 행동 → 검증 루프의 최소 형태입니다.

TypeScript에서도 @trycua/cua-driver의 CuaDriver.create(), ListAppsInput.new({...}), ActionTarget.Window, InputDeliveryMode.Background로 같은 흐름을 씁니다.

실제 예제 2. 일회용 데스크톱 샌드박스를 만들어 조작하고 보여 주기

에이전트에게 내 컴퓨터를 맡기기 불안할 때는 샌드박스를 줍니다. 아래 코드는 Linux 데스크톱 샌드박스를 띄워 터미널을 열고 입력한 뒤, 사람이 지켜볼 수 있는 뷰어 링크를 출력합니다.

python

# desktop_sandbox.py  (pip install cua-sandbox)
import asyncio
from pathlib import Path

from cua_sandbox import Image, Sandbox

# 샌드박스 안에서 터미널 창을 열고 포커스를 준다 (키 입력은 포커스된 창으로 간다)
FOCUS_TERMINAL = (
    "export DISPLAY=:1; setsid -f xfce4-terminal -T demo >/dev/null 2>&1; "
    "xdotool search --sync --onlyvisible --name demo windowactivate --sync"
)


async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:          # 기본은 로컬(gVisor 컨테이너)
        print("viewer:", await sb.viewer_url())                  # 브라우저로 화면을 볼 수 있는 링크

        width, height = await sb.get_dimensions()
        await sb.mouse.click(width // 2, height // 2)

        assert (await sb.shell.run(FOCUS_TERMINAL)).success
        await sb.keyboard.type("echo hello from cua")
        await sb.keyboard.keypress(["ctrl", "a"])               # 단축키는 키 이름 목록으로 보낸다

        Path("desk.png").write_bytes(await sb.screenshot())     # 결과 화면 저장


asyncio.run(main())

코드 설명

Image.linux()는 cua-spacesd가 들어 있는 공식 Ubuntu 24.04 데스크톱 이미지입니다. 그래서 shell, mouse, keyboard, screenshot을 쓸 수 있습니다. cua-spacesd가 없는 이미지라면 이 인터페이스들은 SpacesdNotAvailable을 냅니다.
같은 코드에 on="cloud"만 넘기면 클라우드 샌드박스가 됩니다. 클라우드는 amd64 이미지만 지원하고 macOS는 아직 없습니다.
viewer_url()의 링크는 뷰어 호출만 허가하는 티켓을 담고 있고 기본 1시간 후 만료됩니다. 사람에게 "에이전트가 지금 이 화면에서 일하고 있다"를 보여 줄 때 씁니다.

샌드박스 안의 창·접근성 트리까지 다루려면 cua-sandbox[driver] extra를 설치하고 async with sb.driver.connect() as driver:로 샌드박스 안 Cua Driver의 타입 있는 API를 씁니다. 이 extra는 특정 cua-driver 버전을 고정하므로 쓸 수 있는 메서드를 그 버전 기준으로 확인해야 합니다.

실제 예제 3. 코딩 에이전트에게 샌드박스 하나를 도구로 넘기기

에이전트가 브라우저나 GUI 앱을 시험해 봐야 하는데 내 컴퓨터는 건드리지 않게 하고 싶을 때입니다.

bash

# 1) 이름 있는 샌드박스를 만든다 (지울 때까지 유지)
cua sb create linux --name desk

# 2) 그 샌드박스를 stdio MCP 서버로 Claude Code에 등록
claude mcp add --transport stdio cua-desk -- cua mcp --sandbox desk

# 3) 사람은 브라우저 뷰어로 지켜본다
cua sb view desk

# 4) 작업이 끝나면 정리
cua sb rm -f desk

에이전트는 desk 샌드박스 안에서만 스크린샷·클릭·입력을 하게 됩니다. 실수로 파일을 지워도 샌드박스를 지우고 새로 만들면 됩니다.

실제 예제 4. 샌드박스 안에서 코딩 에이전트를 실행하기

반대로 에이전트 자체를 샌드박스 안에서 돌릴 수도 있습니다. cua SDK는 Claude Code, Codex, Gemini CLI 같은 하네스를 고정된 버전·체크섬으로 설치하고 Agent Client Protocol로 구동합니다.

python

# agent_in_sandbox.py  (pip install cua)
import asyncio
import cua


async def main():
    c = cua.embedded()
    sb = await c.sandboxes().create(cua.SandboxCreateOptions(
        on="local",
        image="ghcr.io/trycua/linux:24.04",
        name="agent-box",
        memory_mb=4096,
        wait_for=[cua.ReadinessProbe(service="env")],  # cua-spacesd가 준비될 때까지 대기
    ))
    agents = await sb.agents()
    run = await agents.run(
        "claude-code",
        "Write primes.py that prints the first 10 primes, then run it.",
        cua.AgentRunOptions(env_from_host=["ANTHROPIC_API_KEY"]),  # 호스트의 키 이름만 지정해 전달
    )
    print("run id:", run.run_id())  # 실행 상태는 샌드박스 안에 남아 다른 클라이언트가 다시 붙을 수 있다


asyncio.run(main())

run.events(cursor, max)로 이벤트를 페이지 단위로 받고, run.send(...)로 후속 지시, run.interrupt()로 진행 중인 턴을 취소합니다. 실행은 샌드박스 안에 살아 있으므로 내 스크립트가 끝나도 계속됩니다. 다 쓴 샌드박스는 cua sb rm이나 SDK의 삭제 호출로 지워야 합니다.

실제 서비스에서는

사용자가 웹 앱에서 "우리 회사 그룹웨어에서 지난주 회의록을 찾아 요약해 줘"라고 요청하면, 백엔드 작업 큐가 요청마다 클라우드 샌드박스(Image.linux(), on="cloud")를 하나 만듭니다. 에이전트 워커는 cua mcp나 SDK로 그 샌드박스만 조작하고, 프런트엔드는 보기 전용 뷰어 링크(SDK의 viewer_url 옵션 view_only, CLI의 cua sb view --view-only)를 iframe에 띄워 사용자가 에이전트의 진행 화면을 실시간으로 봅니다. 작업이 끝나면 워커가 결과 파일을 sb.files로 꺼내 저장하고 샌드박스를 삭제합니다. 워커가 비정상 종료해도 클라우드 샌드박스는 claim_ttl(기본 15분)이 지나면 회수됩니다.

이 구조에서 Cua의 가치는 두 가지입니다. 에이전트의 실행 환경이 사용자별로 격리된다는 점과, 같은 코드를 개발자 노트북(로컬)과 운영(클라우드)에서 on 값만 바꿔 쓴다는 점입니다. 다만 클라우드 사용 시간은 과금되므로, 샌드박스 정리를 async with나 finally로 반드시 보장해야 합니다.

Cua 활용 예시 ③ CI·평가·실전 프로젝트

팀과 서버 환경에서 Cua를 쓰는 방법(CI의 GUI 검증, 클라우드 용량, 에이전트 평가)과, 데스크톱 앱 팀이 Cua를 실제로 도입하는 과정을 다룹니다.

팀·CI·서버 환경에서의 활용

Cua는 서버 애플리케이션이 import하는 라이브러리라기보다, "GUI가 필요한 작업을 서버와 CI에서 돌릴 수 있게 해 주는 실행 기반"입니다.

활용 사례

CI의 데스크톱 앱 E2E: GitHub Actions에서 cua-sandbox 액션으로 Linux 데스크톱 샌드박스를 띄우고, 이번 PR에서 빌드한 바이너리를 주입해 화면 단위로 검사합니다. 액션은 로그, 진단 보고서, 스크린샷을 아티팩트로 올리고 작업이 취소돼도 샌드박스를 지웁니다.
"테스트한 바이너리가 실제로 돈 바이너리인가" 확인: cua doctor --expect로 샌드박스 안에서 실행 중인 파일의 sha256이나 git 커밋을 확인합니다. 옛 데몬이 재시작되지 않아 이전 빌드를 테스트하는 사고를 막습니다.
클라우드 용량: Docker나 KVM이 없는 러너에서는 on: cloud로 클라우드 샌드박스를 씁니다. 동시 실행이 많으면 이름 있는 풀을 만들어 웜 용량을 유지합니다(Cua Fleets).
에이전트 평가: Cua Bench로 작업과 채점 함수를 정의하고, 모델·프롬프트를 바꿀 때마다 같은 데이터셋으로 성공률을 비교합니다.
남는 Mac을 호스트로: cua host setup으로 사무실의 Mac mini를 relay에 연결하면, 팀원과 에이전트가 포트 포워딩 없이 그 기계에 Space를 만들 수 있습니다.

애플리케이션 구조

text

PR / 야간 스케줄
 ↓
GitHub Actions 러너
 ├─ 앱 빌드 (dist/)
 ├─ cua-sandbox 액션: linux 샌드박스 생성 (로컬 Docker 또는 cloud)
 │    ├─ overlay: 빌드 결과를 샌드박스 안에 주입
 │    ├─ guest-setup: 테스트 의존성 설치 (root)
 │    └─ guest-run: 샌드박스 안에서 GUI 스모크 테스트 (Cua Driver SDK)
 ├─ cua doctor --expect: 주입한 빌드가 실제로 실행 중인지 확인
 └─ 아티팩트: 로그 · 스크린샷 · 진단 보고서
 ↓
야간: cb run (Cua Bench) → 에이전트 성공률 리포트

실제 코드

CI에서 샌드박스 띄우기 (최소 형태)

yaml

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@1.97.1   # 액션이 cua CLI를 소스에서 빌드하는 기본 설정
      - uses: trycua/cua/.github/actions/cua-sandbox@<고정한-커밋-sha>
        with:
          image: linux
          run: |
            cua sb exec "$CUA_SANDBOX" uname -a
            cua sb screenshot "$CUA_SANDBOX" -o "$CUA_SANDBOX_ARTIFACTS/desktop.png"

run은 러너에서, guest-run은 샌드박스 안에서 실행됩니다. 공식 예제는 @main을 쓰지만, 의존하는 CI라면 커밋 SHA로 고정하라고 문서가 권합니다.

전용 클라우드 용량 만들기

python

from cua_sandbox import Image, Pool, WarmPoolAutoscaling

# 수요에 따라 0~10대로 늘었다 줄어드는 이름 있는 풀
pool = await Pool.apply(
    Image.linux(),
    name="acme-desktop-e2e",          # 계정을 넘어 전역에서 유일해야 한다
    cpu=4,
    memory_mb=4096,
    autoscaling=WarmPoolAutoscaling(min_pool_size=0, initial_pool_size=2, max_pool_size=10),
)

async with pool.claim(name="job-123") as sb:
    await sb.shell.run("echo hello")

에이전트 평가 실행

bash

uv tool install 'cua-bench[browser]'
cb run first-task --variant-id 0 --oracle                                  # 작업 자체가 맞는지 오라클로 확인
cb run dataset cua-bench-basic --agent cua-agent --model anthropic/claude-sonnet-4-20250514 --attempts 3

어느 계층에 두는가

위치	적합한 Cua 구성 요소	이유
개발자 PC	Cua Driver + MCP	에이전트와 사람이 같은 기계를 쓰며 빠르게 시도
테스트 코드	Driver SDK (in-process)	타입 있는 API와 재관찰로 결정적인 검증
CI 러너	`cua-sandbox` 액션, `cua doctor --expect`	매번 깨끗한 데스크톱, 빌드 일치 확인, 자동 정리
백엔드 워커	cua SDK 클라우드 샌드박스, Fleets 풀	요청별 격리, 웜 용량, TTL로 비용 상한
평가 파이프라인	Cua Bench	같은 채점 함수로 모델·프롬프트 비교

실전 프로젝트 적용: 주문 관리 데스크톱 앱의 GUI 회귀 검증

요구사항

다섯 명이 개발하는 B2B 주문 관리 데스크톱 앱 "Order Desk"(Electron, Linux·Windows 배포)에 Cua를 도입합니다.

PR마다 이번 빌드로 "주문 추가 → 합계 갱신" 핵심 흐름을 GUI 수준에서 검증한다.
테스트 러너에 설치된 다른 버전이 아니라 이번 PR 빌드가 테스트됐다는 증거가 남아야 한다.
실패하면 스크린샷이 PR 아티팩트로 남아야 한다.
매일 밤, 이 앱을 다루는 사내 AI 지원 에이전트가 주요 업무 작업을 얼마나 성공하는지 측정한다.

전체 구조

mermaid

flowchart LR
    subgraph GH[GitHub Actions]
        B[빌드<br/>OrderDesk AppImage]
        A[cua-sandbox 액션]
        D[cua doctor --expect]
        AR[아티팩트<br/>스크린샷 · 로그]
    end

    subgraph SB[Linux 샌드박스]
        SP[cua-spacesd]
        APP[Order Desk]
        T[smoke_test.py<br/>Cua Driver SDK]
        T -->|접근성 조회 · 클릭| APP
    end

    B -->|overlay 주입| A
    A -->|생성 · 정리| SB
    A --> D
    D -->|sha256 확인| SP
    A --> AR

    N[야간 스케줄] -->|cb run| BENCH[Cua Bench<br/>order-tasks]
    BENCH -->|샌드박스마다 채점| SB

폴더 구조

text

order-desk/
├── .github/workflows/
│   ├── desktop-e2e.yml          # PR마다 GUI 스모크 테스트
│   └── agent-eval.yml           # 야간 에이전트 평가
├── e2e/
│   ├── guest-setup.sh           # 샌드박스 안 의존성 설치
│   └── smoke_test.py            # 샌드박스 안에서 실행되는 Cua Driver SDK 테스트
├── bench/
│   └── add-order/
│       ├── main.py              # Cua Bench 작업: setup · solve · evaluate
│       └── pyproject.toml
├── src/                         # Electron 앱 소스
└── package.json

구현

1. 샌드박스 안 준비 스크립트

bash

#!/bin/sh
# e2e/guest-setup.sh : guest-setup 단계에서 root로 실행된다
set -eu
apt-get update
apt-get install -y python3-venv libxi6 at-spi2-core libfuse2
python3 -m venv /opt/e2e
/opt/e2e/bin/pip install cua-driver

2. 샌드박스 안에서 도는 스모크 테스트

python

# e2e/smoke_test.py
import asyncio
import os
import subprocess

from cua_driver import (
    ActionTarget, ClickButton, ClickInput, ClickPosition, CuaDriver,
    GetWindowStateInput, InputDeliveryMode, ListAppsInput, ListWindowsInput,
)

APP = "/opt/order-desk/OrderDesk.AppImage"


def unique(items, what):
    if len(items) != 1:
        raise SystemExit(f"FAIL: expected one {what}, found {len(items)}")
    return items[0]


def by_label(state, label):
    return unique([e for e in state.elements or [] if e.label == label], label)


async def main() -> None:
    # Electron이 접근성 트리를 노출하도록 강제한다
    subprocess.Popen([APP, "--no-sandbox", "--force-renderer-accessibility"], env=os.environ)

    driver = CuaDriver.create()
    try:
        for _ in range(30):  # 창이 뜰 때까지 제한된 횟수만 다시 찾는다
            apps = await driver.list_apps(ListAppsInput())
            running = [a for a in apps.apps if a.name == "Order Desk" and a.running]
            if running:
                windows = await driver.list_windows(ListWindowsInput(pid=running[0].pid, on_screen_only=True))
                if windows.windows:
                    break
            await asyncio.sleep(1)
        app = unique(running, "Order Desk process")
        window = unique([w for w in windows.windows if w.title.startswith("Order Desk")], "main window")

        capture = GetWindowStateInput(
            pid=app.pid, window_id=window.window_id, session=None, query=None,
            include_accessibility_tree=True, include_screenshot=True,
            screenshot_out_file="/tmp/e2e/after.png", max_elements=None, max_depth=None,
            max_dimension=None,
        )

        before = await driver.get_window_state(capture)
        total_before = by_label(before, "Order total").value

        await driver.click(ClickInput(
            target=ActionTarget.WINDOW(pid=app.pid, window_id=window.window_id),
            position=ClickPosition.ELEMENT(element_token=by_label(before, "Add sample order").element_token),
            delivery_mode=InputDeliveryMode.BACKGROUND,
            session=None, button=ClickButton.LEFT, count=1,
        ))

        after = await driver.get_window_state(capture)
        total_after = by_label(after, "Order total").value
        if total_after == total_before:
            raise SystemExit(f"FAIL: total stayed {total_before}")
        print(f"PASS: total {total_before} -> {total_after}")
    finally:
        await driver.shutdown()


asyncio.run(main())

3. PR 워크플로

yaml

# .github/workflows/desktop-e2e.yml
name: desktop-e2e
on: [pull_request]

jobs:
  gui-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm run build:appimage          # dist/OrderDesk.AppImage
      - uses: dtolnay/rust-toolchain@1.97.1
      - uses: trycua/cua/.github/actions/cua-sandbox@<고정한-커밋-sha>
        with:
          image: linux
          overlay: |
            order-desk=dist/OrderDesk.AppImage:/opt/order-desk/OrderDesk.AppImage
            smoke=e2e/smoke_test.py:/opt/e2e/smoke_test.py
            setup=e2e/guest-setup.sh:/opt/e2e/guest-setup.sh
          guest-setup: sh /opt/e2e/guest-setup.sh
          guest-run: |
            export DISPLAY=:1
            mkdir -p /tmp/e2e
            /opt/e2e/bin/python /opt/e2e/smoke_test.py
          run: |
            cua sb screenshot "$CUA_SANDBOX" -o "$CUA_SANDBOX_ARTIFACTS/final.png"

4. 야간 에이전트 평가 작업 (Cua Bench)

python

# bench/add-order/main.py : cb task create 로 만든 뼈대에 업무 내용을 채운다
import cua_bench as cb

@cb.tasks_config(split="train")
def load(): ...        # 변형(고객사·품목·수량 조합)과 실행할 머신(Linux 샌드박스) 정의

@cb.setup_task(split="train")
async def start(task_cfg, session): ...     # 앱 설치·실행, 주문 데이터 초기화

@cb.solve_task(split="train")
async def solve(task_cfg, session): ...     # 오라클: 정답 순서로 주문을 추가

@cb.evaluate_task(split="train")
async def evaluate(task_cfg, session): ...  # 앱의 저장 파일에서 주문이 정확히 한 건 늘었으면 1.0

yaml

# .github/workflows/agent-eval.yml (핵심 단계만)
      - run: uv tool install cua-bench
      - run: cb run bench/add-order --oracle                       # 작업이 깨지지 않았는지 먼저 확인
      - run: cb run bench/add-order --agent cua-agent --model anthropic/claude-sonnet-4-20250514
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

실제 실행 흐름

"합계가 갱신되지 않는 회귀"가 들어간 PR을 예로 듭니다.

사용자 행동: 개발자가 합계 계산 로직을 리팩터링한 PR을 올립니다.
빌드와 샌드박스 생성: 러너가 AppImage를 빌드하고, cua-sandbox 액션이 로컬 Docker에 Linux 데스크톱 샌드박스를 만듭니다.
빌드 주입과 확인: overlay가 AppImage와 테스트 파일을 샌드박스 안에 원자적으로 넣고 sha256을 기록합니다. 액션이 cua doctor로 주입한 파일이 실제로 쓰이는지 확인합니다.
샌드박스 안 준비: guest-setup이 Python 가상 환경과 cua-driver를 설치합니다.
GUI 검증: smoke_test.py가 앱을 띄우고 Cua Driver SDK로 창을 찾아 "Add sample order"를 백그라운드로 클릭합니다. 새 스냅샷에서 "Order total" 값이 그대로여서 FAIL: total stayed 0으로 종료합니다.
결과 반영: run 단계가 마지막 화면을 스크린샷으로 남기고, 액션이 로그·진단 보고서와 함께 아티팩트로 올린 뒤 샌드박스를 지웁니다. 리뷰어는 PR에서 실패 화면을 바로 봅니다.
야간 평가와의 연결: 수정이 머지된 뒤 야간 agent-eval이 오라클 → 에이전트 순으로 cb run을 실행합니다. 오라클은 통과하는데 에이전트 성공률이 떨어지면 앱이 아니라 UI 라벨 변경이 에이전트를 헷갈리게 한 것인지 trajectory로 확인합니다.

샌드박스 이미지 구성(설치된 Python, AT-SPI 세션, 디스플레이 번호)은 이미지 버전에 따라 달라질 수 있습니다. 처음 도입할 때는 cua sb create linux --name ci --wait desktop → cua sb shell ci로 같은 단계를 손으로 한 번 실행해 보고 guest-setup을 맞추는 것이 안전합니다.

Cua 장단점과 대안 비교

Cua를 쓰면 일반적인 화면 자동화와 무엇이 달라지는지, 장점과 단점, 그리고 모델 제공사의 computer use 도구·브라우저 자동화·샌드박스 서비스·RPA와 비교해 상황별로 무엇을 고를지 다룹니다.

좌표 기반 자동화와 무엇이 달라지나

항목	스크린샷 + 좌표 클릭 (pyautogui 등)	Cua
요소 지정	모델이 추정한 x, y 좌표	접근성 트리의 `element_token`, 필요할 때만 같은 스크린샷의 픽셀
입력 전달	실제 마우스·키보드 (포커스 이동)	기본은 대상 창에만 백그라운드 전달
사람과 공유	실행 중에는 컴퓨터를 못 씀	지원되는 앱에서는 사람과 동시에 작업 가능
성공 판정	예외가 없으면 성공으로 간주	행동마다 `effect`·`escalation`, `verify_state`, 재관찰
지원 안 되는 경우	조용히 빗나감	구조화된 거부(`refused`)와 다음 단계 제안
실행 환경	보통 호스트 그대로	호스트, 로컬 컨테이너·VM, 클라우드를 같은 API로
권한 통제	없음 (스크립트가 할 수 있는 것은 다 함)	`standard` / `bounded` 매니페스트 / `unrestricted`
기록	직접 구현	trajectory 녹화, 영상 렌더링, Computer History(프리뷰)
시작 비용	매우 낮음	설치·OS 권한·개념 학습 필요

장점과 단점

장점

화면을 "의미"로 다룬다

접근성 트리 덕분에 "금액 입력창", "저장 버튼"처럼 역할과 이름으로 요소를 고릅니다. 창 위치나 해상도가 바뀌어도 같은 요소를 찾을 수 있고, 모델이 비슷한 모양의 다른 버튼을 고르는 실수가 줄어듭니다.

사람의 작업을 방해하지 않는다

백그라운드 전달은 실제 포인터와 포커스를 건드리지 않습니다. 에이전트용 커서 오버레이가 따로 그려지므로 사람은 무엇이 일어나는지 보면서 자기 일을 계속할 수 있습니다. 데스크톱 자동화 도구 중에서 이 점을 핵심으로 내세우는 경우는 드뭅니다.

"보냈다"와 "됐다"를 구분한다

모든 행동은 결과를 다섯 단계(confirmed, partial, unverifiable, suspected_noop, refused)로 보고하고, confirmed는 증거 없이는 낼 수 없도록 계약에 묶여 있습니다. 검증을 위한 verify_state도 따로 있습니다. 자동화의 가장 흔한 사고인 "조용한 실패"를 줄여 줍니다.

모델과 에이전트를 가리지 않는다

MCP 서버로 붙기 때문에 Claude Code, Codex, Cursor, 사내 에이전트 어디서나 씁니다. 모델을 바꿔도 실행 계층은 그대로입니다.

같은 코드로 로컬과 클라우드

샌드박스는 on="local"과 on="cloud"만 바꿔 같은 코드로 씁니다. 개발 중에는 비용 없이 로컬에서, 운영이나 대량 실행은 클라우드에서 돌릴 수 있습니다.

지원 범위를 정직하게 공개한다

플랫폼·앱 종류·전달 방식 조합마다 실제 앱 상태 변화로 검증한 결과를 표로 공개하고, 안 되는 조합은 거부로 돌려줍니다. "될 것 같은데 가끔 안 되는" 영역이 줄어듭니다.

단점

플랫폼과 앱에 따라 한계가 크다

Wayland에서는 가려진 창에 raw 입력을 보낼 수 없고, Windows에서는 관리자 권한으로 실행된 앱에 입력할 수 없으며, 캔버스 앱과 게임은 백그라운드 입력을 무시합니다. Linux는 컴포지터마다 지원 수준이 다르고 KDE·Hyprland는 실험 단계입니다.

설치와 권한 설정이 번거롭다

macOS 손쉬운 사용·화면 기록 권한, Linux 데스크톱 세션과 AT-SPI, Windows 대화형 세션이 필요합니다. 헤드리스 서버에서 바로 쓰는 도구가 아니고, 권한이 꼬이면 tccutil로 초기화해야 하는 경우도 있습니다.

변화가 매우 빠르다

Driver는 몇 주 사이에 0.28에서 0.33으로 올라갔고, 2026년 10월 개편에서 샌드박스 SDK는 기본 실행 위치가 로컬로 바뀌고 일부 전송 방식이 제거되는 Breaking Change가 있었습니다. 외부 튜토리얼의 API가 현재와 다른 경우가 많습니다.

구성 요소가 많고 경계가 복잡하다

Driver, SDK, cua-spacesd, Spaces, Fleets, Lume, Bench, CUA-S1이 한 저장소에 있고 패키지 이름도 여러 개입니다. 무엇이 무엇에 의존하는지 이해하는 데 시간이 듭니다.

라이선스가 한 가지가 아니다

대부분은 MIT지만 Cua Spaces 관련 구성(앱, cua-spacesd, Keyvault, teleport 등)은 FSL-1.1-MIT이고, 선택 설치하는 cua-perception 확장은 AGPL 구성 요소를 포함합니다. 재배포나 호스팅 서비스를 만든다면 구성 요소별로 확인해야 합니다.

비슷한 도구와 비교

도구	특징	장점	단점	추천 상황
Cua	모델 중립 데스크톱 드라이버 + 로컬·클라우드 샌드박스 + 평가 도구	접근성 기반 조작, 백그라운드 전달, 행동별 검증 신호, 호스트·샌드박스 모두 지원	플랫폼별 한계, 권한 설정, 빠른 변화	네이티브 데스크톱 앱을 에이전트가 다뤄야 하고, 검증과 격리가 중요한 경우
모델 제공사의 computer use 도구 (Anthropic, OpenAI 등)	모델이 스크린샷을 보고 클릭·입력 행동을 제안하는 API 기능	모델과 함께 최적화됨, 시작 예제가 풍부	행동을 실제로 실행할 환경과 실행기는 직접 준비해야 함, 기본은 스크린샷·좌표 중심	특정 모델 하나로 프로토타입을 빠르게 만들 때. 실행 계층으로 Cua를 함께 쓰는 조합도 가능
Playwright / 브라우저 에이전트 도구	DOM과 브라우저 프로토콜로 웹 페이지를 조작	빠르고 정확함, 테스트 생태계가 성숙	브라우저 밖의 네이티브 앱은 다루지 못함	작업이 웹 안에서 끝나는 경우
클라우드 데스크톱 샌드박스 서비스 (E2B Desktop 등)	원격 VM 데스크톱과 스크린샷·입력 SDK	인프라 관리 불필요, 확장 쉬움	보통 클라우드 전용, 내 컴퓨터의 앱은 대상이 아님	에이전트를 항상 원격 격리 환경에서만 돌리는 서비스
RPA 도구 (UiPath, Power Automate Desktop 등)	사람이 설계한 흐름을 반복 실행하는 업무 자동화

위 비교는 각 도구의 일반적인 성격을 기준으로 한 것이며, 세부 기능은 버전마다 달라질 수 있습니다.

어떤 것을 선택하면 될까?

Cua

에이전트가 네이티브 데스크톱 앱을 다뤄야 하고, 사람과 같은 컴퓨터를 공유하거나 격리된 데스크톱이 필요하며, "정말 반영됐는지"를 확인하는 것이 중요할 때 고릅니다. 처음에는 Cua Driver 하나만 설치해 MCP로 붙이고, 위험도가 높아질 때 샌드박스와 bounded 모드를 더하는 순서가 좋습니다.

모델 제공사의 computer use 도구

이미 특정 모델을 쓰고 있고, 짧은 데모나 프로토타입을 빠르게 만들고 싶다면 그 모델의 도구 예제가 가장 빠른 길입니다. 다만 행동을 실행할 환경(가상 디스플레이, 입력 실행기)은 직접 준비해야 하므로, 그 부분을 Cua의 샌드박스나 Driver로 채우는 조합을 검토할 만합니다.

Playwright·브라우저 에이전트

작업이 브라우저 안에서 끝난다면 이쪽이 더 단순하고 빠르며 안정적입니다. Cua도 브라우저 도구(CDP 기반)를 갖고 있지만, 웹 전용이라면 굳이 데스크톱 드라이버를 거칠 이유가 없습니다.

클라우드 샌드박스 서비스

에이전트를 항상 원격에서만 돌리고, 내 컴퓨터의 앱을 다룰 일이 없다면 관리형 서비스가 운영 부담이 적습니다. 로컬 실행이나 macOS 게스트가 필요하다면 Cua가 유리합니다.

RPA

"매일 같은 화면에서 같은 순서로" 일하는 업무라면 모델 판단이 오히려 변동성을 만듭니다. 결정적인 RPA 흐름이 맞고, 예외 처리처럼 판단이 필요한 부분만 에이전트에 넘기는 구성이 현실적입니다.

Cua 관찰·행동·검증 루프 깊이 보기

Cua Driver가 한 번의 행동을 어떻게 관찰하고, 어떤 경로로 전달하고, 결과를 어떤 계약으로 보고하는지 다룹니다. 이 루프를 이해하면 "클릭은 성공했는데 아무 일도 안 일어났다" 같은 문제를 왜 Cua가 구조적으로 다르게 다루는지 알 수 있습니다.

왜 이 루프가 Cua의 핵심인가

화면 자동화의 어려움은 클릭을 "보내는 것"이 아니라 클릭이 "먹혔는지" 아는 것에 있습니다. 운영체제에 이벤트를 보내는 함수는 거의 항상 성공을 반환합니다. 그러나 앱이 그 이벤트를 무시했을 수도, 다른 창이 받았을 수도, 값은 들어갔지만 저장은 안 됐을 수도 있습니다.

Cua Driver는 이 문제를 세 단계로 쪼개고, 각 단계에 규칙을 둡니다.

단계	규칙	지키지 않으면 생기는 일
관찰	행동 전에 정확한 창 하나를 관찰한다	예전 화면이나 다른 창을 기준으로 행동
행동	최신 스냅샷의 토큰으로, 정확한 대상에, 한 번만	엉뚱한 요소 클릭, 중복 입력
검증	행동의 결과 신호와 작업 완료 조건을 따로 확인	"성공"이라 믿고 다음 단계로 진행

관찰: 무엇을 받고, 무엇을 믿지 말아야 하는가

정확한 대상 고르기

관찰은 list_apps → list_windows({pid}) → get_window_state({pid, window_id}) 순서로 좁혀 갑니다. 기억해 둔 PID가 아직 살아 있다고 가정하지 않고, 창 목록에서 첫 번째 항목을 무작정 고르지도 않습니다. 창 제목, 위치, 앱 identity는 후보를 고르는 데 쓰지만 최종 지정은 항상 window_id입니다. list_windows의 z_index는 클수록 앞에 있는 창이고, null은 0이 아니라 "모름"입니다.

`get_window_state`의 응답 읽기

필드	의미	주의
`elements[]`	요소 행. `element_token`, `role`, `label`, `value`, `actions`, `enabled`, `frame`, `screenshot_frame` 등	MCP에서는 `tree_markdown`을 파싱하지 말고 `structuredContent.elements`를 씀
`frame`	화면 좌표	데스크톱 단위 행동의 좌표계
`screenshot_frame`	같은 응답 스크린샷의 픽셀 좌표	창 단위 픽셀 행동의 좌표계
`degraded`, `degraded_reason`	접근성 브리지 문제 등으로 품질이 떨어짐	빈 트리가 "요소 없음"을 뜻하지 않음

캡처 실패와 빈 접근성 트리는 서로 다른 실패입니다. 화면 기록 권한이 없으면 트리만 오고 스크린샷은 오지 않습니다. 이 경우 픽셀 행동으로 넘어가면 안 됩니다. 유효한 창 이미지가 없으면 그 창의 픽셀 행동도 없다는 것이 규칙입니다.

세션과 토큰의 수명

MCP 연결이나 SDK 런타임마다 암묵적인 세션이 하나 생깁니다. 세션은 연결 종료, end_session, 또는 5분간 아무 호출이 없으면 정리되고, 이때 그 세션의 element_token도 무효가 됩니다. 세션은 수명 관리용 이름표이지 권한이나 캡처 범위가 아닙니다. 그래서 "세션을 만들었으니 이 창만 다룬다"가 아니라, 매 행동마다 대상을 다시 지정합니다.

행동: 대상, 위치, 전달 방식

하나의 행동이 담는 정보

입력 도구(click, type_text, press_key, hotkey, scroll, drag, move_cursor)는 호출 하나에 대상 하나를 지정합니다.

json

{
  "target": { "kind": "window", "pid": 844, "window_id": 10725 },
  "element_token": "s0000002a:14",
  "delivery_mode": "background",
  "session": "run-1"
}

구성	값	설명
대상 (`target`)	`window` 또는 `desktop`	데스크톱 대상은 `{"kind":"desktop","display_id":"primary"}`이며 항상 포그라운드
위치	`element_token` 또는 `x`, `y`	픽셀은 같은 창의 최신 스크린샷 기준. 창 좌표에 창 위치를 더하지 않음
전달 (`delivery_mode`)	`background`(기본) 또는 `foreground`	포그라운드는 창을 앞으로 가져오고 끝나면 포커스를 되돌림

Action ladder

백그라운드 요소 행동이 안 되면 단계를 올립니다. 단, 응답이 단계를 제안할 뿐 자동으로 올라가지는 않습니다.

mermaid

flowchart TD
    A[요소 + 백그라운드<br/>접근성 동작] -->|refused 또는 suspected_noop| B[픽셀 + 백그라운드<br/>같은 스크린샷 좌표]
    B -->|브라우저 탭이면| C[페이지<br/>CDP로 DOM 동작]
    B -->|네이티브 앱이면| D[포그라운드<br/>창 활성화 후 실행]
    C -->|실패| D
    A -->|confirmed| V[검증]
    B -->|unverifiable| V
    C -->|결과| V
    D -->|결과| V
    D -.->|허가 없음| S[멈추고 사람에게 확인]

요소, 백그라운드: macOS AXPerformAction, Windows UI Automation, Linux AT-SPI 동작을 씁니다. Driver가 값 읽기 등으로 스스로 결과를 확인할 수 있는 유일한 단계입니다.
픽셀, 백그라운드: 같은 스크린샷의 좌표로 보냅니다. 키보드 도구는 포커스를 위해 먼저 클릭합니다. 픽셀로 지정해도 내부적으로 접근성 hit-test를 쓸 수 있으므로, 실제로 어떤 경로였는지는 응답의 route로 확인합니다.
페이지: 브라우저 탭이라면 창 포커스 없이 CDP로 DOM에 동작합니다. 브라우저 조작은 항상 정확한 (pid, window_id) 바인딩에서 시작합니다.
포그라운드: delivery_mode: "foreground"로 재시도합니다. 사용자의 화면을 침범하므로 별도 허가가 있을 때만 씁니다. "백그라운드가 안 된다"는 사실이 포그라운드 허가를 뜻하지는 않습니다.

결과 계약: `ActionResult`

Cua Driver의 Rust 계약 크레이트(cua-driver-contract)는 행동 결과를 다음 타입으로 정의합니다. 이 타입에서 JSON 스키마와 Python·TypeScript 바인딩이 생성되므로, MCP·CLI·SDK가 같은 구조를 봅니다.

rust

// libs/cua-driver/rust/crates/cua-driver-contract/src/outputs.rs (요약)
pub enum ActionEffect { Confirmed, Partial, Unverifiable, SuspectedNoop, Refused }

pub enum ActionRoute { Accessibility, SyntheticEvents, GlobalInput, SystemApi, Dom, TrustedInput }

pub enum ActionEscalationTarget { Pixel, Foreground, Page, Session }
pub enum ActionEscalationReason {
    RouteUnavailable, DeliveryFailed, EffectUnconfirmed, SuspectedNoop, PermissionRequired,
}

pub struct ActionResult {
    pub effect: ActionEffect,                     // 필수
    pub route: ActionRoute,                       // 필수: 실제로 쓴 전달 경로
    pub delivery: Option<ActionDelivery>,         // 백그라운드·포그라운드, 전달된 개수
    pub evidence: Option<Vec<ActionEvidence>>,    // 값 읽기, 창 변화 같은 근거
    pub escalation: Option<ActionEscalation>,     // 다음 단계 제안 (target + reason)
    pub summary: Option<String>,                  // 사람이 읽는 요약
    pub error: Option<ActionError>,               // refused 일 때만: code + hint
}

이 구조에서 눈여겨볼 것은 불변 조건(invariant)입니다. 같은 파일의 validate_invariants()는 다음 조합을 오류로 거부합니다.

불변 조건	의미
`confirmed`인데 `evidence`가 비어 있음 → 오류	증거 없는 "확인됨"은 존재할 수 없다
`partial`인데 `delivered_count`가 없음 → 오류	부분 성공이면 어디까지 갔는지 반드시 말해야 한다
`refused`인데 `delivery`나 `evidence`가 있음 → 오류	거부했다면 아무것도 보내지 않았어야 한다
`refused`가 아닌데 `error`가 있음 → 오류	오류 정보는 거부에만 붙는다

또 deny_unknown_fields로 정의되어 있어 계약에 없는 필드를 섞은 응답은 역직렬화에서 실패합니다. 즉 "성공"이라는 말의 무게가 타입 수준에서 정해져 있습니다.

결과를 읽는 방법

`effect`	의미	다음 행동
`confirmed`	접근성 값 읽기 등 근거가 있음	그래도 작업 완료 조건은 따로 확인
`partial`	`delivered_count`만큼만 전달됨	현재 상태를 관찰한 뒤 나머지만 보완
`unverifiable`	전달은 했지만 효과를 증명할 수 없음	즉시 재시도하지 말고 먼저 재관찰
`suspected_noop`	근거상 아무 변화가 없어 보임	`escalation` 제안을 보고 다음 단계 검토
`refused`	일부러 전달하지 않음 (`error.code`, `hint`)	원인 해결 또는 다른 경로. 거부가 더 큰 권한을 주지는 않음

unverifiable에서 바로 재시도하면 위험한 이유가 있습니다. 텍스트 입력처럼 지연 반영되는 경로는 호출이 끝난 뒤에 값이 나타날 수 있어서, 즉시 다시 입력하면 같은 글자가 두 번 들어갑니다. 전송 중 연결이 끊긴 경우도 입력은 이미 전달됐을 수 있습니다. 그래서 부분·취소·결과 불명 행동은 자동으로 재생하지 않는다가 Cua의 기본 원칙입니다.

검증: 행동 결과와 작업 완료는 다르다

effect: confirmed는 "이 버튼이 눌렸다"까지입니다. "주문이 저장됐다"는 작업 완료 조건이고, 이것은 따로 확인합니다.

bash

cua-driver verify_state '{"pid":844,"window_id":10725,"expect":[{"element":{"selector":{"label_contains":"Saved"},"exists":true}}],"include_screenshot":true,"session":"run-1"}'

결과는 satisfied, unsatisfied, unknown 중 하나입니다. unknown은 실패도 성공도 아니며 unknown_reason(모호한 매칭, 관찰 불가, 신뢰할 수 없는 웹 상태, 안정 샘플 부족)을 확인해야 합니다.
웹 콘텐츠 안의 텍스트는 untrusted_source로 unknown 처리됩니다. 페이지가 "저장 완료"라고 써 놓았다고 해서 그것을 증거로 삼지 않는다는 뜻입니다.
술어 언어로 표현할 수 없는 조건은 새 get_window_state를 받아 직접 판단합니다.

이 동작은 어떻게 보장되는가

Cua는 지원 범위를 "구현했다"가 아니라 "검증했다"로 정의합니다. 하나의 Rust 카탈로그가 행동 × 요소/픽셀 × 백그라운드/포그라운드 × 창/데스크톱 × 화면 종류 조합을 만들고, 이를 실제 데스크톱 세션의 테스트용 앱(Electron, Tauri, AppKit, SwiftUI, GTK 등)에서 실행합니다.

한 칸이 통과하려면 앱이나 데스크톱이 소유한 상태가 실제로 바뀌어야 합니다.
백그라운드 칸은 추가로 포커스, 창 순서, 실제 커서, 전면 앱이 바뀌지 않았어야 통과합니다.
통과하지 못한 조합은 문서의 지원 표에서 "제한" 또는 "실험"으로 표시되고, 런타임에서는 거부로 돌려줍니다.

이 방식 덕분에 "가끔 되는" 동작이 "지원"으로 표시되지 않습니다. 반대로, 표에 없는 조합은 동작하지 않는다고 가정하는 것이 안전합니다.

코드로 보는 최소 루프

Driver SDK로 위 원칙을 지키는 클릭 헬퍼를 만들면 다음과 같습니다. 포그라운드 승격은 호출자가 명시적으로 허가했을 때만 합니다.

python

from cua_driver import (
    ActionEffect, ActionTarget, ClickButton, ClickInput, ClickPosition,
    DriverError, InputDeliveryMode,
)


async def click_and_verify(driver, pid, window_id, snapshot, label, check, allow_foreground=False):
    """label 요소를 클릭하고 check(새 스냅샷)가 참인지 확인한다. 자동 재생은 하지 않는다."""
    before = await snapshot()
    [element] = [e for e in before.elements or [] if e.label == label]
    target = ActionTarget.WINDOW(pid=pid, window_id=window_id)

    for mode in [InputDeliveryMode.BACKGROUND] + ([InputDeliveryMode.FOREGROUND] if allow_foreground else []):
        try:
            result = await driver.click(ClickInput(
                target=target,
                position=ClickPosition.ELEMENT(element_token=element.element_token),
                delivery_mode=mode, session=None, button=ClickButton.LEFT, count=1,
            ))
        except DriverError.Tool:
            continue  # refused: 아무것도 전달되지 않았으므로 다음 단계를 검토해도 안전하다

        after = await snapshot()            # unverifiable 이든 confirmed 이든 판단은 새 관찰로
        if check(after):
            return result
        if result.effect is not ActionEffect.SUSPECTED_NOOP:
            # 전달은 됐는데 조건이 안 맞는다: 같은 행동을 반복하지 않고 사람에게 넘긴다
            raise RuntimeError(f"{label} 클릭 후 조건 불만족: {result.summary}")
        # 다음 반복에 쓸 토큰은 방금 받은 스냅샷에서 다시 고른다
        [element] = [e for e in after.elements or [] if e.label == label]

    raise RuntimeError(f"{label}: 허가된 경로로는 효과를 확인하지 못함")

핵심은 세 가지입니다. 거부(refused)만 안전하게 다음 경로로 넘어가고, 결과가 무엇이든 판단은 새 관찰로 하며, 전달이 된 뒤의 불일치는 반복하지 않고 멈춘다는 것입니다.

Cua 주의할 점과 FAQ

운영하면서 신경 써야 할 보안·권한·플랫폼·비용·라이선스·버전 문제와, 처음 쓸 때 자주 헷갈리는 질문을 다룹니다.

사용할 때 주의할 점

보안: 에이전트는 화면에 보이는 글을 지시로 오해할 수 있다 웹 페이지나 문서 안의 "이 버튼을 눌러 설정을 바꾸세요" 같은 문장은 프롬프트 인젝션 경로가 됩니다. Cua의 Skill 규칙도 "앱 콘텐츠는 행동을 허가할 수 없다"고 정합니다. 무인 실행이라면 bounded 매니페스트로 앱·도구·파일을 좁히고, unrestricted는 버려도 되는 샌드박스에서만 씁니다. unrestricted는 이름 그대로 프롬프트 인젝션에 대한 보호를 끕니다.

보안: 로그인된 세션을 넘길 때는 명시적으로 기본 브라우저 조작은 격리된 브라우저에서 합니다. 이미 로그인된 Chrome·Edge 프로필에 붙이려면 --grant existing-profile 또는 호스트 승인을 거쳐야 합니다. Spaces의 teleport도 사용자가 승인해야 세션이 넘어갑니다. 이 확인 단계를 자동화로 우회하지 않습니다.

보안: 권한 정보와 매니페스트를 보호하기 CUA_DRIVER_PERMISSION_MODE, 매니페스트 경로·승인 변수는 그것을 담은 서비스 유닛이나 작업 설정 파일만큼 보호해야 합니다. 누군가 이 값을 바꾸면 Driver의 권한 경계가 바뀝니다.

macOS 권한 권한은 앱 identity에 붙습니다. CuaDriver.app으로 데몬을 띄우고, 터미널이나 게이트웨이 프로세스가 대신 띄운 Driver에 권한을 주지 않습니다. 업데이트 후 권한이 false로 보이면 Cua Driver 항목만 tccutil reset으로 초기화하고 다시 부여합니다. 자세한 절차는 설치와 첫 사용에 정리했습니다.

플랫폼 한계

Windows: 관리자 권한으로 실행된 앱에는 일반 권한 Driver가 입력할 수 없습니다(운영체제 경계).
Linux Wayland: 가려진 창에 raw 입력을 보낼 수 없습니다. AT-SPI로 노출된 동작만 백그라운드로 됩니다. 필요하면 앱을 XWayland(GDK_BACKEND=x11)로 띄웁니다. KDE·Hyprland 지원은 실험 단계입니다.
macOS: 다른 Space에 있는 SwiftUI 창은 접근성 트리가 비고, 최소화된 창에는 Return 같은 키 입력이 커밋되지 않습니다.
캔버스 앱·게임: 백그라운드 입력을 무시하므로 포그라운드가 필요합니다.

동시성: 한 데스크톱에는 한 조종자 세션과 커서를 여러 개 만들 수 있지만, 포커스·키보드 입력·앱 상태·스냅샷 캐시는 공유됩니다. 두 에이전트가 같은 창을 관찰하면 서로의 토큰을 무효로 만듭니다. 병렬 작업은 데스크톱(샌드박스)을 나눠서 합니다.

비용

클라우드 샌드박스는 실행 중인 시간만큼 과금됩니다. 프로세스가 죽어도 claim_ttl(기본 15분)까지는 남으므로 async with나 finally로 정리를 보장합니다.
관리형 풀은 30분 유휴 후 삭제되지만, 직접 만든 풀은 직접 지우거나 TTL을 걸어야 합니다.
로컬 macOS VM 이미지는 디스크를 크게 차지합니다. cua cache du로 확인합니다.
에이전트가 스크린샷을 자주 보면 모델 토큰 비용이 빠르게 늘어납니다. 가능한 경우 include_screenshot:false와 query로 관찰 범위를 줄입니다.

라이선스 대부분은 MIT입니다. 다만 Cua Spaces 관련 구성(Spaces 앱, cua-spacesd, Keyvault, teleport, Cua Volume 등)은 FSL-1.1-MIT로, 사용·자체 호스팅은 자유지만 경쟁 호스팅 서비스는 제한되며 각 릴리스는 2년 후 MIT가 됩니다. 선택 설치하는 cua-perception 확장은 AGPL-3.0 구성 요소(OmniParser 아이콘 검출기)를 포함하므로, 재배포하거나 네트워크 서비스로 제공하면 소스 공개 의무가 생길 수 있습니다. CUA-S1 모델·데이터셋은 각 카드의 라이선스를 따로 확인합니다.

Breaking Change와 Deprecated 사용 방식 (2026년 10월 기준)

cua-sandbox 0.9: 새 Rust cua SDK 위로 옮겨지면서 Sandbox.create가 기본적으로 로컬에서 실행됩니다(클라우드는 local=False 또는 on="cloud"). cua_sandbox.localhost 모듈과 computer_server·http·local·websocket 전송이 제거되었고, 로컬 기계 제어는 Cua Driver가 맡습니다.
cua-agent의 omni extra가 제거되었습니다. 의존하던 cua-som은 Deprecated이며 AGPL입니다.
Python cua 패키지는 예전 메타 패키지(0.1.x)를 대체한 Rust SDK 바인딩입니다. 예전 글의 pip install cua 예제는 현재와 다를 수 있습니다.
Driver의 행동 도구는 element_index를 받지 않고 element_token만 받습니다. capture_mode 인자는 무시됩니다.
Driver Python SDK의 옛 MCP facade(CuaDriver.stdio(), AsyncCuaDriver)는 제거되었습니다. 에이전트는 cua-driver mcp에 직접 붙습니다.
샌드박스 kind·runtime·on의 평탄한 키워드(pool=, 등)는 경고와 함께 동작하지만 로 옮기는 것이 현재 방식입니다.

유지보수와 버전 고정 프로젝트는 매우 활발하며 제품별로 하루에도 여러 번 릴리스됩니다. CI와 운영에서는 Driver·SDK·액션을 버전이나 커밋으로 고정하고, 고정한 릴리스의 체크섬을 확인합니다. Computer History 같은 기능은 nightly 채널 프리뷰이므로 운영 환경 기준으로 삼지 않습니다.

자주 헷갈리는 부분

Q. Cua는 AI 에이전트인가요? 모델을 포함하나요?

아닙니다. Cua의 기본 역할은 에이전트가 쓰는 컴퓨터와 도구입니다. 무엇을 할지는 Claude Code, Codex 같은 에이전트와 그 모델이 판단합니다. 저장소에는 cua-agent라는 에이전트 프레임워크와 CUA-S1 소형 모델도 있지만, 둘 다 선택 사항이고 Cua Driver나 샌드박스를 쓰는 데 필요하지 않습니다.

Q. Driver의 Python SDK를 에이전트 코드에서 쓰면 되나요, MCP를 써야 하나요?

에이전트라면 MCP(cua-driver mcp)를 씁니다. 에이전트 프레임워크는 이미 MCP 클라이언트를 갖고 있고, Driver Skill도 MCP·CLI를 기준으로 작성되어 있습니다. Python·TypeScript SDK는 테스트 코드나 데스크톱 앱처럼 사람이 작성한 결정적인 코드가 Driver를 직접 호출할 때 씁니다. 공식 문서도 "언어 패키지는 클라이언트 애플리케이션용이며 에이전트용이 아니다"라고 구분합니다.

Q. 클릭이 `confirmed`였는데 왜 또 검증해야 하나요?

confirmed는 "이 행동이 의도한 요소에 효과를 냈다는 근거가 있다"는 뜻이지 "작업이 끝났다"는 뜻이 아닙니다. 저장 버튼이 눌렸어도 서버 오류로 저장이 실패했을 수 있습니다. 작업의 완료 조건은 verify_state나 새 스냅샷으로 따로 확인합니다. 자세한 내용은 관찰·행동·검증 루프 깊이 보기에서 다룹니다.

Q. 백그라운드가 안 되면 자동으로 포그라운드로 바뀌나요?

아닙니다. 응답의 escalation은 제안일 뿐이고, 포그라운드 전달은 사용자의 화면과 포커스를 침범하므로 따로 허가가 있어야 합니다. SDK에서도 InputDeliveryMode.BACKGROUND로 요청한 행동은 실패해도 포그라운드로 재시도하지 않습니다.

Q. 샌드박스를 쓰면 Cua Driver는 필요 없나요?

샌드박스 안에서도 Driver가 일합니다. 샌드박스 이미지의 cua-spacesd가 입력과 접근성 조회를 샌드박스 안의 Cua Driver에 맡깁니다. 차이는 Driver가 내 컴퓨터를 조작하느냐, 격리된 컴퓨터를 조작하느냐입니다. 반대로 cua-sandbox는 샌드박스만 다루고, 내 로컬 기계를 조작하려면 Cua Driver를 직접 씁니다.

Q. Cua Fleets와 `on="cloud"`는 다른 서비스인가요?

같은 클라우드입니다. on="cloud"(또는 local=False)로 만들면 SDK가 이미지와 크기별로 관리형 풀을 자동으로 만들고 유휴 시 지웁니다. 이름 있는 풀, 고정 웜 용량, Terraform, 클레임별 비밀값이 필요할 때 Fleets를 직접 다룹니다.

Q. GitHub 릴리스에 "Pre-release"라고 되어 있는데 운영에 써도 되나요?

cua-driver-rs-v0.33.3 같은 일반 SemVer 태그는 안정 릴리스입니다. 모노레포에 제품이 여러 개라서 저장소 전체의 "Latest" 표시가 제품 사이를 오가지 않도록 Pre-release 라벨을 붙였을 뿐입니다. npm과 PyPI에도 정식 버전으로 올라갑니다. 실제 불안정 채널은 nightly-로 시작하는 태그입니다.

Q. macOS 게스트를 클라우드에서 띄울 수 있나요?

2026년 10월 기준 클라우드 샌드박스는 amd64 Linux·Windows 이미지만 지원하고 macOS는 아직 없습니다. macOS 샌드박스는 Apple Silicon Mac에서 Lume으로 로컬 실행합니다.

truncated

warm=

cloud=CloudOptions(...)

개요

30초 요약

어떤 라이브러리인가?

주요 사용 사례

어떤 문제를 해결하는가?

상황 예시

일반적인 구현 방식

이 방식에서 발생하는 문제

Cua를 사용하면

왜 주목받고 있는가?

언제 사용하면 좋은가?

언제 사용하지 않는 것이 좋은가?

한눈에 정리

핵심 정리

한 문장으로

이것만 기억하기

Cua 핵심 개념과 동작 구조

용어 한눈에 보기

1. Cua Driver (에이전트의 손과 눈)

쉽게 설명하면

개발 관점에서는

예제

핵심

2. 관찰: 접근성 트리 + 스크린샷

쉽게 설명하면

개발 관점에서는

예제

핵심

3. element_token (스냅샷에 묶인 요소 이름표)

쉽게 설명하면

개발 관점에서는

핵심

4. 백그라운드 전달과 Action ladder

쉽게 설명하면

개발 관점에서는

핵심

5. 권한 모드 (무엇까지 허용할 것인가)

쉽게 설명하면

개발 관점에서는

예제

핵심

6. 샌드박스와 cua-spacesd (써도 되는 컴퓨터)

쉽게 설명하면

개발 관점에서는

예제

핵심

7. 주변 구성 요소: Spaces, Lume, Cua Bench, CUA-S1

8. 전체 동작 구조

Cua 설치와 첫 사용

무엇을 설치할지 먼저 고르기

설치 1. Cua Driver

설치 확인

설치 2. 에이전트에 연결

설치 3. 샌드박스용 cua CLI와 SDK

가장 간단한 예제

에이전트로 계산기 조작하기

코드로 샌드박스 하나 띄우기

설치할 때 주의할 점

Cua 활용 예시 ① 내 컴퓨터의 앱을 에이전트에게 맡기기

예제 1. 경비 내역을 데스크톱 정산 앱에 입력하기

요구사항

구현

실행 흐름

코드 설명

왜 이렇게 사용하는가?

예제 2. 같은 작업을 사람 없이 돌리기

요구사항

구현

왜 이렇게 사용하는가?

함께 알아 두면 좋은 기능

Cua 활용 예시 ② 애플리케이션 코드에서 샌드박스 다루기

활용할 수 있는 기능

실제 예제 1. Driver SDK로 데스크톱 앱 동작 검증하기

실제 예제 2. 일회용 데스크톱 샌드박스를 만들어 조작하고 보여 주기

실제 예제 3. 코딩 에이전트에게 샌드박스 하나를 도구로 넘기기

실제 예제 4. 샌드박스 안에서 코딩 에이전트를 실행하기

실제 서비스에서는

Cua 활용 예시 ③ CI·평가·실전 프로젝트

팀·CI·서버 환경에서의 활용

활용 사례

3. `element_token` (스냅샷에 묶인 요소 이름표)

설치 3. 샌드박스용 `cua` CLI와 SDK

`get_window_state`의 응답 읽기

결과 계약: `ActionResult`

Q. 클릭이 `confirmed`였는데 왜 또 검증해야 하나요?

Q. Cua Fleets와 `on="cloud"`는 다른 서비스인가요?