cua 딥다이브
— AI에게 컴퓨터를 빌려주고, 행동의 결과를 확인하는 법

1프로젝트 한줄 요약

cua는 AI 에이전트가 쓸 컴퓨터를 만들고 연결하며, 그 안의 앱을 관찰·조작하고 평가하도록 돕는 도구 모음입니다. 이름의 CUA는 Computer Use Agent를 뜻합니다. 여기서 컴퓨터 사용은 “텍스트를 답한다”를 넘어 창을 찾고, 버튼을 누르고, 파일을 저장하는 행동입니다.

예를 들어 “계산기에서 6 × 7을 계산해 줘”라는 요청을 생각해 보세요. 언어 모델은 다음 행동을 정하지만 계산기 창의 실제 위치는 모릅니다. 드라이버는 창과 접근성 정보를 읽고 입력을 전달합니다. 마지막에는 화면이나 앱 상태에서 42를 확인해야 합니다. 요청이 접수되었다는 응답만으로 계산 성공을 선언할 수는 없습니다.

이 저장소에서 배울 핵심은 AI의 판단과 컴퓨터의 실행, 실행 결과의 검증을 서로 다른 책임으로 나누는 방법입니다.

처음 읽을 때 범위를 좁히는 법

이 글은 libs/cua의 수명 관리와 cua-driver-core의 대상 검증을 중심으로 읽습니다. Teleport, 메시 네트워크, 모델 학습은 연결 지점까지 다룹니다. 거대한 저장소를 처음부터 모두 이해하려 하기보다 “컴퓨터를 만들고 → 현재 상태를 읽고 → 한 번 행동하고 → 결과를 확인한다”는 한 흐름을 따라가면 됩니다.

2왜 주목받는가

2-1. 화제의 배경과 확인 가능한 근거

2026-10-23 기준 GitHub Trending Rust Monthly 4위이며, 스타는 30,747개입니다. 다만 순위와 스타만으로 사용량이나 안정성을 증명할 수는 없습니다. 주목받는 이유는 다음 기능 조합에서 추론할 수 있습니다. 이는 코드와 공개 설명을 바탕으로 한 해석이며, 유입 경로를 측정한 결과는 아닙니다.

• 실행 환경까지 다룹니다. 클릭 API와 함께 이미지, VM·컨테이너 실행, 준비 상태 확인, 실패 시 정리까지 포함합니다.
• 브라우저 밖으로 확장합니다. Windows UI Automation, macOS Accessibility, Linux AT-SPI 등 OS의 앱 정보와 입력 체계를 연결합니다.
• 사람과 에이전트의 공동 작업을 겨냥합니다. README의 Spaces 설명은 별도 커서와 화면 공유, 앱 세션 이동을 주요 기능으로 내세웁니다. 실제 가능 범위는 OS와 앱에 따라 다릅니다.
• 평가를 제품 경계에 넣습니다. Bench의 과제 평가기와 Driver의 데스크톱 테스트는 도구 응답을 넘어 앱 상태를 확인하도록 설계되어 있습니다.

cua의 매력은 클릭 명령의 개수보다, 실행 환경을 준비하는 단계부터 결과를 증명하는 단계까지 연결한다는 데 있습니다.

2-2. 경쟁·인접 도구와 비교하기

다음은 기능의 중심을 비교한 표입니다. 성능 순위표가 아니며, 이 표에는 같은 과제로 측정한 속도·정확도 수치를 담지 않았습니다. 브라우저만 다루는 일이면 전용 도구가 더 간단할 수 있습니다.

비교 근거: Playwright 공식 소개, Browser Use 공식 시작 안내, cua의 플랫폼 지원표. 각 프로젝트의 범위에 관한 비교이며 “더 빠르다”거나 “더 정확하다”는 주장을 하지 않습니다.

2-3. 최신 커밋이 알려 주는 좋은 개발 습관

커밋 cdda707의 제목은 Browser Use CLI 비교 경로를 버전 고정과 문제가 있으면 중단하는 사전 점검으로 준비했다는 뜻입니다. 여기서 비교 경로는 같은 과제를 서로 다른 도구로 수행하는 실험의 한 갈래입니다.

libs/cua-driver-bench/automated-eval/macos_bench/pins.json은 Browser Use를 0.13.11, Python을 3.12로 지정하고 wheel 파일과 스킬의 SHA-256을 기록합니다. 반면 같은 폴더의 libs/cua-driver-bench/automated-eval/macos_bench/browser_use_cli.py에서 preflight()는 다음처럼 동작합니다.

# browser_use_cli.py의 동작을 한국어로 풀어 쓴 축약 예시
def preflight():
    return [(ARM, "fail", "운영 사전 점검이 아직 구현되지 않음")]

즉, 준비된 코드가 있다는 사실과 실행 가능한 지원이 완료되었다는 사실은 다릅니다. 이 시점의 비교 경로는 점검을 통과할 수 없습니다. 초보자는 함수의 이름만 읽지 말고 반환값과 호출자의 중단 조건까지 확인하는 습관을 배울 수 있습니다.

2-4. 소개 문구와 현재 소스를 구분하기

3기술 스택 전체 지도

3-1. 백엔드와 시스템 계층

3-2. Python은 SDK 사용과 평가·연구를 연결합니다

Python SDK의 “기본 의존성이 없다”는 말은 순수 Python 구현이라는 뜻이 아닙니다. 배포되는 네이티브 라이브러리가 실제 기능을 수행할 수 있습니다. 패키지 관리자 의존성과 운영체제 바이너리 의존성은 다른 목록입니다.

3-3. 프론트엔드는 한 종류가 아닙니다

같은 이름의 Spaces라도 빌드 대상이 다릅니다. React 버전 하나를 찾아 “프론트엔드는 React 19.1”로 끝내면 다른 앱의 의존성을 놓칩니다. 폴더별 manifest가 버전 판단의 단위입니다.

3-4. 인프라·빌드·CI

• 도구 버전: libs/cua/rust-toolchain.toml은 Rust 1.97.1을 고정합니다. 루트 Node 패키지는 Prettier ^3.6.2와 pnpm 9.0.4를 선언하며, 모든 앱의 패키지 관리자가 같은 버전인 것은 아닙니다.
• 이미지: libs/images/linux/Dockerfile은 기본 Ubuntu 24.04, XFCE, Xvfb, AT-SPI, PipeWire 등을 설치합니다. 브라우저·GUI·접근성·오디오를 함께 준비하는 데스크톱 이미지입니다.
• 브라우저 고정: 같은 Dockerfile의 Chromium 기본 major는 amd64 156, arm64 155입니다. 정확한 빌드 번호가 아니며, 저장소에서 해당 major가 사라지면 대체하고 CI가 변경을 알리도록 주석과 로직을 둡니다.
• 잠금 검사: .github/workflows/ci-lockfiles.yml은 Cargo·npm·pnpm·uv 잠금 파일과 선언의 일치를 검사합니다. “컴파일 성공”과 “의존성 해석이 재현된다”는 서로 다른 검사입니다.
• SDK 검사: .github/workflows/ci-cua-sdk.yml은 fmt·clippy·Rust 테스트·WASM 빌드·언어 바인딩 점검을 구성합니다. 일반 PR의 Rust 행렬은 조건에 따라 Linux만 돌 수 있어, 녹색 표시 하나가 모든 OS 검증을 뜻하지 않습니다.
• 계약 검사: libs/cua/proto/buf.yaml은 STANDARD·COMMENTS lint와 FILE·WIRE_JSON breaking 규칙을 설정합니다. API 설명과 호환성을 자동 점검 대상으로 만듭니다.

4아키텍처 심화 분석

4-1. 시스템 전체 구조

위 구조는 대표적인 연결 경로를 단순화한 것입니다. Cua Driver는 샌드박스 없이 현재 컴퓨터의 앱에도 사용할 수 있습니다. 반대로 샌드박스는 cua-spacesd 없이도 실행할 수 있습니다. 예를 들어 웹 서버 컨테이너가 준비되었는지는 해당 서비스의 HTTP 응답만 확인하면 됩니다.

cua daemon과 cua-spacesd는 별개입니다. 전자는 클라이언트 쪽에서 샌드박스 상태와 연결을 여러 프로세스가 공유하게 합니다. 후자는 대상 컴퓨터 안에서 파일·프로세스·화면 기능을 제공합니다. 둘을 하나로 읽으면 “내 PC의 프로세스”와 “게스트 안의 프로세스”를 혼동하게 됩니다.

샌드박스가 실행 중이라는 사실, 제어 서버에 연결된다는 사실, 앱의 작업이 성공했다는 사실은 각각 따로 확인해야 합니다.

4-2. 패턴 ① 포트와 어댑터: 실행 환경을 바꾸는 인터페이스

libs/cua/crates/cua-sandbox-core/src/runtime.rs의 LocalRuntime은 상위 계층이 로컬 실행 환경에 요구하는 계약입니다. 포트는 “무슨 기능을 요구하는가”, 어댑터는 “어느 제품으로 구현하는가”에 해당합니다.

// LocalRuntime에서 핵심 메서드만 발췌
#[async_trait]
pub trait LocalRuntime: Send + Sync {
    fn backend(&self) -> String;
    async fn start(&self, spec: &LocalStartSpec)
        -> RuntimeResult<LocalInstance>;
    async fn stop(&self, name: &str) -> RuntimeResult<()>;
    async fn delete(&self, name: &str) -> RuntimeResult<()>;
}

Send + Sync는 이 객체를 여러 비동기 작업·스레드 사이에서 다룰 수 있도록 요구하는 Rust 제약입니다. 모든 메서드가 모든 환경에서 가능한 것은 아닙니다. 예를 들어 기본 fork()와 checkpoint() 구현은 RuntimeError::Unsupported를 돌려줍니다. 지원하지 않는 기능을 조용히 흉내 내지 않습니다.

libs/cua/crates/cua-vmm/src/auto.rs의 select()와 doctor()는 이미지 종류, 호스트 OS·아키텍처, 실행기 가용성을 판단합니다. macOS 게스트는 지원되는 Mac의 Lume, Linux·Windows VM은 우선 QEMU, 컨테이너는 Docker API 엔진과 gVisor·runc 경로를 사용합니다. QEMU를 사용할 수 없고 Lume가 준비되어 있거나 준비 가능한 경우 Linux ARM64 VM은 Lume로 실행할 수 있습니다. 자동 선택은 이미지와 호스트의 제약을 없애는 기능이 아닙니다.

생성은 시작 명령 하나가 아니라 작은 트랜잭션입니다

libs/cua/crates/cua-sandbox-core/src/sandbox.rs의 Sandboxes::create()를 따라가면 다음 순서가 보입니다.

1. apply_placement()와 validate_sidecars()로 조합을 검증합니다.
2. build_image()로 이미지를 준비하고 create_local() 또는 create_contrib()로 분기합니다. 직접 연결 대상은 여기서 만들지 않습니다.
3. wait_ready()로 사용자가 지정한 probe를 확인합니다. 이미지 다운로드는 게스트 부팅에 쓸 준비 시간 예산과 구분합니다.
4. declares_spacesd()가 참이면 추가로 wait_spacesd()를 호출합니다. 이미지가 서비스를 선언하고, env 서비스가 있으며, 시작 명령을 대체하지 않은 경우입니다. Health가 응답하는지 확인하므로 데스크톱의 준비 상태는 별도로 살펴야 합니다.
5. 준비 실패 시 새로 만든 대상을 정리합니다. 기존에 같은 이름으로 있던 대상은 보존하며, keep_on_failure 같은 정책도 반영합니다.

create_cancellable()와 DiscardGuard::drop()는 요청이 취소되거나 future가 버려질 때도 생성 중 자원을 정리하는 경로를 둡니다. Rust의 Drop 안에서는 비동기 정리를 직접 기다릴 수 없어 현재 Tokio 런타임을 얻을 수 있을 때 정리 작업을 예약합니다. “스코프를 벗어났다”와 “원격 자원 삭제가 완료되었다”를 구별해야 하는 이유입니다.

출처: 생성·준비·취소 로직, 실행기 선택.

4-3. 패턴 ② 파사드와 브리지: 같은 기능에 여러 입구 만들기

libs/cua/crates/cua-sdk/src/native/cua.rs에는 Cua 객체 뒤의 두 실행 방식이 enum으로 표현됩니다. 파사드는 복잡한 내부 구조 앞에 일관된 입구를 세우는 패턴입니다.

// 소스의 내부 Backend 정의
#[derive(Clone)]
pub(crate) enum Backend {
    Embedded(Runtime),
    Daemon(DaemonClient),
}

Cua::embedded()는 같은 프로세스에 런타임을 만들고, Cua::connect()는 daemon 연결 객체를 만들며, 실제 연결은 첫 호출 때 확인합니다. Cua::auto()는 로컬 daemon의 가용성을 판단하는 기본 진입점입니다. 어떤 연결 오류든 무조건 숨기는 함수는 아닙니다. 앱 번들에 포함된 빌드와 맞지 않는 daemon 등에는 별도 오류 경로가 있습니다.

libs/cua/crates/cua-sdk/src/lib.rs는 이 workspace에서 UniFFI export를 모으는 공개 경계입니다. 오류를 CuaError로 정리하고, 외부 언어 호출이 사용하는 Tokio 런타임도 SDK가 소유합니다. Python 이용자가 Rust 실행기를 직접 준비할 필요를 줄이는 설계입니다.

화면 쪽에도 같은 아이디어가 있습니다. apps/cua-spaces-web/src/bridge/transport.ts의 HostTransport는 post()와 listen()을 요구합니다. webkitTransport()는 Swift 호스트의 메시지 핸들러를, electronTransport()는 Electron preload의 호출 채널을 사용합니다. 화면은 같은 요청·이벤트 형식을 다룰 수 있습니다.

출처: SDK 진입점, 웹 화면의 호스트 브리지.

4-4. 패턴 ③ 버전 붙은 핸들: “그때 본 버튼”을 가리키기

화면을 읽은 뒤 창이 바뀌면 이전 좌표나 요소 번호가 다른 버튼을 가리킬 수 있습니다. libs/cua-driver/rust/crates/cua-driver-core/src/element_token.rs는 스냅샷 번호와 요소 인덱스를 결합한 토큰을 만듭니다.

// element_token.rs의 형식
pub fn token_for(snapshot_id: u32, element_index: usize) -> String {
    format!("{}:{element_index}", format_snapshot_id(snapshot_id))
}
// snapshot_id = 0x1234, element_index = 42
// 결과: s00001234:42

parse_token()은 이 형식을 해석합니다. libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs의 SnapshotStore::resolve()는 실제 보관 중인 스냅샷과 연결하고, 토큰의 창이 명시한 window_id와 다르면 conflicting_element_target으로 거절합니다. 사라진 스냅샷에 대한 호출은 stale_element_token을 돌려 새 상태를 읽도록 유도합니다.

LRU_CAP_PER_PID = 8은 프로세스별 스냅샷 보관 상한입니다. 이 토큰은 로그인 비밀값이나 암호화된 인증서가 아닙니다. 관찰한 요소를 특정 스냅샷·창에 연결하는 참조입니다. 저장소에 토큰이 남아 있다는 사실만으로 앱의 현재 상태가 같다고 보장되지는 않습니다.

SnapshotStore::screenshot_context()도 중요한 경계입니다. 스크린샷 소유 세션과 배율, 창 크기를 함께 관리하고, 프레임이 없거나 다른 세션의 것이면 screenshot_context_missing을 반환할 수 있습니다. 숫자 두 개의 좌표에도 어느 창의 어떤 크기 이미지에서 나온 좌표인가라는 문맥이 필요합니다.

출처: 요소 토큰, 스냅샷 해석과 좌표 문맥.

4-5. 패턴 ④ 정책과 실행 분리: 확신할 수 없으면 거절하기

libs/cua-driver/rust/crates/cua-driver-core/src/background_input.rs의 decide_background_input()는 대상에 관한 사실을 받아 Execute 또는 Refuse 결정을 반환합니다. 이 함수는 정책을 계산하며, 그 자체가 입력을 보내는 함수는 아닙니다. 해당 파일의 사실 모델에는 macOS WindowServer·AX 특성이 반영되어 있으므로 세부 조건을 모든 OS에 그대로 일반화하면 안 됩니다.

libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs의 Tool trait와 ToolRegistry::register()·invoke()는 각 도구를 등록하고 공통 호출 경계를 형성합니다. trait의 has_independent_input_lane() 기본값은 false입니다. 호출자가 “독립 입력”이라고 주장하는 것만으로는 부족하며, 구현이 이를 보장해야 한다는 뜻입니다.

출처: 백그라운드 입력 정책, 도구 계약과 등록소.

4-6. 평가 루프에서 같은 원칙 확인하기

libs/cua-bench/cua_bench/runners.py의 run_single_task()는 에이전트의 행동 뒤에 평가기를 호출합니다. 평가기가 없거나 보상이 숫자가 아니거나, 유한한 [0, 1] 범위를 벗어나면 오류로 처리합니다. 성공 기준은 이 함수에서 reward >= 0.5로 설정되어 있습니다. 모든 벤치마크에 통용되는 자연법칙이 아니라 이 실행기의 정책입니다.

finally에서 환경을 닫다가 실패하면 기존 성공도 실패로 바꾸고 보상을 0으로 바꿉니다. 에이전트가 “완료”를 말하는 것, 평가기가 결과를 인정하는 것, 실행 환경이 정리되는 것을 함께 추적하는 예입니다. 이 설계를 읽으며 자기 자동화에도 행동·채점·정리를 각각 기록해 보세요.

5디렉토리 구조 해부

이 트리는 학습 경로를 보여 주기 위해 일부 항목만 담았습니다. libs/cua와 libs/cua-driver/rust는 독립 Cargo workspace입니다. 루트에 모든 Rust 코드를 한 번에 빌드하는 단일 workspace가 있다고 가정하지 마세요.

또한 libs/cua/typescript와 libs/typescript는 다른 위치입니다. 루트 개발 안내는 통합 cua SDK의 위치를 libs/cua로 지정합니다. 예전 예제나 패키지 이름을 발견하면 바로 현재 공개 API라고 가정하지 말고, 해당 폴더의 README·manifest·CI가 어떤 소비자를 대상으로 하는지 확인해야 합니다.

5-1. 직접 센 코드 규모

커밋 cdda707의 Git 추적 일반 파일은 9,219개입니다. 언어별 수치는 확장자를 기준으로 파일을 골라 줄바꿈을 세었으며, 마지막 줄에 줄바꿈이 없어도 한 줄로 계산했습니다. 빈 줄·주석·테스트·예제·생성 바인딩·미러 코드를 포함합니다. 심볼릭 링크와 Git 내부 파일은 제외한 수치입니다.

이 표는 GitHub의 언어 비율과 같은 통계가 아닙니다. GitHub의 언어 판정은 별도 규칙을 사용하며, 물리적 줄 수는 코드의 난도나 직접 작성한 분량을 뜻하지 않습니다. .mdx·JSON·잠금 파일·이미지 등도 위 언어 표에 합산하지 않았습니다.

5-2. 원하는 기능에서 파일로 거꾸로 찾기

한 함수에서 다음 책임으로 넘어가는 지점에 표시를 해 두면, 큰 파일을 모두 읽지 않고도 한 동작을 추적할 수 있습니다.

6학습 포인트 (기술별)

6-1. Rust: trait와 enum으로 가능한 행동을 모델링하기

LocalRuntime은 기능 계약을, Backend는 실행 방식의 선택지를 나타냅니다. trait는 구현을 늘리는 축이고 enum은 미리 정한 경우를 나누는 축입니다. 어느 것을 택했는지 이유를 생각하며 읽어 보세요.

Arc<dyn LocalRuntime>은 여러 소유자가 같은 구현 객체를 공유하고, 구체적인 실행기 타입은 인터페이스 뒤에 감춘다는 뜻입니다. 반면 Backend::Embedded와 Backend::Daemon은 코드가 반드시 구별해 처리할 두 경로입니다.

6-2. 비동기 프로그래밍: 시간 예산과 취소를 함께 다루기

wait_ready()는 준비되지 않은 상태와 복구할 수 없는 상태를 나눕니다. 단순히 10초 기다린 뒤 성공이라고 하는 방식은 컴퓨터 속도·다운로드·앱 기동 시간에 따라 흔들립니다. wait_spacesd()는 인증 오류를 즉시 반환하고, 종료한 인스턴스도 조기에 감지합니다.

같은 루프의 재시도 간격은 250ms입니다. 하지만 이 숫자만 복사하는 것이 핵심은 아닙니다. 마감 시각, 재시도할 오류, 즉시 중단할 오류, 마지막 실패 이유를 함께 보관하는 것이 핵심입니다.

# 소스의 아이디어를 옮긴 의사코드 · 특정 SDK API가 아닙니다
마감 = 현재시각 + 제한시간
반복:
    결과 = 상태확인()
    성공이면 반환
    인증오류 또는 대상종료이면 즉시 실패
    현재시각이 마감을 넘으면 마지막원인과 함께 실패
    250밀리초 대기

6-3. Protobuf와 gRPC: 기능을 계약으로 공개하기

libs/cua/proto/cua/env/v1/system.proto의 GetCapabilitiesResponse에는 protocol_version, protocol_revision, features, limits가 있습니다. 클라이언트는 버전 문자열만 비교하는 대신 어떤 기능이 있고 어떤 제한이 있는지 물을 수 있습니다.

메시지의 필드 번호는 통신 계약의 일부입니다. 새 필드를 추가하는 작업과 기존 필드의 의미를 바꾸는 작업은 호환성 위험이 다릅니다. 이 저장소가 buf breaking과 생성 코드의 변경 여부를 검사하는 이유를 해당 필드 목록에서 이해할 수 있습니다.

6-4. OS 자동화: 좌표에 문맥을 붙이기

접근성 트리는 버튼의 역할·이름·값을 알려 주는 구조입니다. 픽셀은 이미지 위의 위치입니다. 접근성에 원하는 정보가 없으면 픽셀 경로가 필요할 수 있지만, 그 좌표는 창 이동·크기·DPI·스크린샷 축소의 영향을 받습니다.

libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs의 ScreenshotContext와 ZoomContext::zoom_to_window()를 함께 읽어 보세요. 확대 이미지 좌표를 원래 창 좌표로 바꾸는 식은 origin + coordinate × scale_inv입니다. 같은 점을 여러 계층에서 중복 변환하면 오차가 커집니다.

실습으로 가로 1,000픽셀 창을 500픽셀 이미지로 표시했다고 가정하세요. 이미지의 x=120은 원래 x=240입니다. 창을 다시 확대했거나 이미지를 잘랐다면 배율뿐 아니라 원점도 필요합니다. 숫자 두 개를 전달하는 API보다 좌표계까지 담은 타입이 안전합니다.

6-5. TypeScript와 SwiftUI: 화면과 호스트의 책임 나누기

웹 화면의 HostTransport를 읽으며 요청 전송과 이벤트 구독을 분리한 이유를 찾아보세요. 버튼 클릭은 요청을 만들지만, 장시간 진행되는 연결이나 생성 상태는 나중에 이벤트로 도착할 수 있습니다.

apps/cua-spaces-macos/Package.swift는 SwiftUI 셸이 공유 Rust 앱 코어를 연결한다고 설명합니다. 화면마다 같은 규칙을 다시 쓰면 한쪽만 수정되는 문제가 생깁니다. 공통 코어와 얇은 호스트 계층은 이를 줄이는 방향입니다. 다만 UI 브리지의 형식과 스레드·객체 수명도 별도로 맞춰야 합니다.

6-6. Python 평가: 행동과 채점을 독립시키기

libs/cua-bench/cua_bench/decorators.py는 tasks_config, setup_task, solve_task, evaluate_task로 함수의 역할을 표시합니다. 데코레이터는 함수에 _td_type과 _td_split 같은 메타데이터를 붙입니다.

Environment.make_from_module()이 그 표시를 읽고, Environment.evaluate()는 현재 과제와 세션을 평가 함수에 넘깁니다. _call_function()은 반환값이 awaitable인지 확인해 동기·비동기 함수를 모두 처리합니다. 과제 작성자와 실행기의 책임을 분리한 예입니다.

libs/cua-bench/cua_bench/core.py의 make()는 과제 디렉터리의 진입 파일(예: libs/cua-bench/tasks/miniwob/main.py)을 Python 모듈로 불러와 실행합니다. 따라서 과제는 단순 데이터 파일만이 아닙니다. 공개 데이터셋을 받더라도 평가 함수와 실행 환경 설정을 읽어야 재현성과 동작을 이해할 수 있습니다.

좋은 평가기는 에이전트의 완료 선언을 믿는 대신, 과제가 요구한 결과를 독립적인 증거로 확인합니다.

6-7. 빌드와 테스트: 한 가지 초록불로 모든 것을 설명하지 않기

docs/contributing/TESTING.md는 단일 루트 명령으로 모든 패키지·데스크톱·VM·이미지를 증명할 수 없다고 설명합니다. 문법·타입 검사, 프로토콜 검사, 실제 앱 조작은 서로 다른 실패를 찾습니다.

실습 아이디어는 “클릭 함수가 성공을 반환했는데 앱 값은 안 바뀌었다”는 가상 결함을 만드는 것입니다. 어떤 테스트가 이를 잡고 어떤 테스트는 지나치는지 적으면, 테스트를 많이 만드는 것과 강한 관찰 경계에 테스트를 두는 것의 차이가 보입니다.

7하드웨어 / 시스템 요구사항

7-1. 어떤 경로를 쓰는지 먼저 고르세요

cua를 쓰는 데 필요한 자원은 선택한 실행 환경과 모델에 달려 있으며, 하나의 GPU·메모리 요구사항으로 전체 저장소를 설명할 수 없습니다.

7-2. 코드에 실제로 있는 기본값

libs/cua/crates/cua-sandbox-core/src/sandbox.rs의 CreateOptions::new()는 다음 값을 사용합니다. 이는 샌드박스에 전달하는 기본 설정이며 호스트 PC의 공식 최소 사양은 아닙니다. 실행기에 따라 자원 제한의 적용 방식도 다를 수 있습니다.

// CreateOptions::new()의 일부 설정
os: "linux".into(),
cpus: 2,
memory_mb: 4096,
ready_timeout: Duration::from_secs(600),
kind: Kind::Auto,
runtime: Runtime::Auto,

VM 하나에 약 4GiB를 할당하면 호스트 OS와 편집기·브라우저에 남길 메모리도 계산해야 합니다. 예를 들어 16GB 호스트에서 한 개를 먼저 실습하고, 여러 VM을 병렬 실행할 때는 수를 늘려 가며 여유를 측정하는 계획을 세울 수 있습니다. 이 예시는 학습용 자원 배분 예이며 공식 최소 사양이나 성능 실측값은 아닙니다.

7-3. 디스크는 이미지 크기와 여유 공간을 더해서 봅니다

libs/cua/crates/cua-vmm/src/disk.rs의 기본 최소 여유 공간은 5GiB, 경고 기준은 20GiB입니다. 이미지 크기를 미리 모를 때 쓸 추정값도 따로 있습니다.

이 값들은 다운로드의 실제 용량이나 설치 후 총 사용량을 보장하지 않습니다. ensure_space_in()은 필요한 바이트와 남겨 둘 최소 공간을 함께 확인합니다. 이미지 캐시·복제 디스크·기록 영상이 늘어나는 실험에서는 실제 사용량을 별도로 측정해야 합니다.

7-4. 시스템 권한과 개발 도구

• macOS: Driver 조작에는 Accessibility와 Screen Recording 권한이 필요합니다. 잠금 화면이나 일부 다른 Space의 창은 정상 로그인 화면과 같은 조건이 아닙니다.
• Windows: 데스크톱 E2E에는 활성 콘솔 또는 RDP 세션이 필요합니다. 낮은 무결성 프로세스가 관리자 권한 앱을 조작할 수 있다고 가정하면 안 됩니다.
• Linux: X11·Sway·GNOME·KDE·Hyprland를 구별하세요. 현재 문서에서 네이티브 Wayland는 CUA_DRIVER_RS_ENABLE_WAYLAND=1로 선택하며, 컴포지터별 지원 수준이 다릅니다.
• Rust 개발: 해당 workspace의 Rust toolchain과 개발 가이드에 맞는 protoc·buf 등을 확인합니다. 배포된 바이너리 사용과 소스 빌드의 도구 목록은 다릅니다.
• Python 개발: 기본 cua SDK 패키지는 >=3.10, Bench는 >=3.12,<3.14입니다. 모든 Python 경로에 같은 하한을 적용하지 마세요.

원격 제어 포트도 자원과 함께 확인하세요. libs/cua-spacesd/crates/cua-spacesd-server/src/config.rs의 default_listen()은 토큰이 있으면 모든 인터페이스, 없으면 루프백을 기본값으로 택합니다. check_bind_policy()는 명시적인 bootstrap·토큰 대기 모드 등의 예외가 없을 때 토큰 없는 외부 바인딩을 거절합니다. 로컬 접속 성공을 외부 공개 설정의 안전성으로 일반화하지 않는 것이 중요합니다.

8직접 해볼 수 있는 실습 과제

1~3번은 저장소 코드나 설치 스크립트를 실행하지 않고도 수행할 수 있습니다. 별도 연습용 파일이나 문서로 시작하세요. 4~5번의 실제 실행은 공식 가이드에 맞춘 독립 실습 환경이 준비되었을 때 진행합니다.

실습의 완료 기준은 명령이 오류 없이 끝났다는 사실보다, 예상한 상태 변화와 실패 조건을 설명하고 확인할 수 있는가입니다.

9관련 기술 심화 학습 로드맵

먼저 Python이나 TypeScript 중 익숙한 언어로 전체 흐름을 이해한 뒤 Rust 내부로 들어가는 순서가 좋습니다. Rust 문법을 처음부터 모두 끝내야 이 저장소를 읽을 수 있는 것은 아닙니다. 매주 작지만 설명 가능한 산출물을 남기세요.

학습의 진도는 읽은 파일 수보다, 한 번의 행동이 어떤 경계를 지나고 어디서 실패할 수 있는지 설명하는 능력으로 확인하세요.

관심 분야별 다음 갈림길

• 백엔드·시스템: cua-vmm의 실행기 선택에서 시작해 이미지 digest 고정, 준비 상태, 취소 후 정리를 더 깊게 봅니다.
• 앱·프론트엔드: HostTransport에서 요청·이벤트를 추적하고, 공통 Rust 앱 코어와 호스트별 셸이 규칙을 어떻게 공유하는지 읽습니다.
• 자동화: 요소 토큰·좌표 문맥·백그라운드 정책에서 시작해 사용 중인 OS 한 개의 실제 구현으로 내려갑니다.
• AI·평가: 먼저 독립 평가기와 재현 가능한 과제를 만들고, 이후 CUA-S1의 모델·데이터 카드와 학습 코드로 넘어갑니다.

10핵심 키워드 사전

11참고 링크

11-1. 프로젝트와 사용 안내

• trycua/cua 공식 저장소 — 제품별 입구와 전체 설명.
• 분석 기준 커밋의 전체 소스 — 이 글의 파일·설정·함수 설명 기준.
• cua 공식 문서 — 설치할 때는 사용하려는 구성요소의 현재 문서도 확인.
• Cua Driver 시작 안내 — 계산기 과제, 권한, 에이전트 연결.
• Cua SDK 시작 안내 — 샌드박스 사용 흐름.
• Cua Spaces 시작 안내 — 사용자 앱에서 Space 만들기.
• Lume 시작 안내 — Apple Silicon의 VM 경로.
• Cua Spaces v0.13.1 릴리스 — 2026-10-23 GitHub 기준 최신 릴리스 항목.

11-2. 코드와 설계를 이어 읽는 링크

• SDK Cargo manifest · Driver Cargo manifest — 서로 다른 workspace와 버전.
• LocalRuntime 계약 · 생성·준비·취소 구현 — 환경을 바꾸고 자원을 정리하는 설계.
• SDK 공개 경계 · embedded·daemon 실행 방식 — 언어 경계와 프로세스 경계.
• SystemService 계약 — 기능 협상·버전·제한 정보.
• cua-spacesd 서버 안내 · 바인딩·토큰 정책 — 현재 서버 경계.
• Bench 실행과 채점 · 과제 함수의 역할 표시 — 행동과 평가 분리.
• Browser Use 비교 경로의 사전 점검 — 준비 단계와 지원 완료 구별.
• 테스트 지도 · 분석 시점 플랫폼 지원표 — 무엇을 어디에서 검증하는지.
• 구성요소별 라이선스 안내 · 미디어 프로토콜 crate 선언 — 루트 README와 다른 라이선스 표기 확인.
• CUA-S1 연구 안내 — 특화 모델의 범위와 별도 가중치.

11-3. 기반 기술의 공식 학습 자료

• The Rust Programming Language — 소유권·enum·trait·오류 처리.
• Tokio 공식 튜토리얼 — 비동기 작업·공유 상태·네트워크.
• UniFFI 공식 안내 — Rust와 외부 언어의 바인딩.
• Protocol Buffers 개요 · gRPC 공식 문서 — 메시지 계약과 원격 호출.
• Apple Virtualization 문서 · gVisor 문서 — 서로 다른 실행·격리 기반.
• Playwright 공식 소개 · Browser Use 공식 시작 안내 — 웹 중심 도구와의 범위 비교.

현재 상태 (2026-10-23 확인)