Offscreen이 에이전트의 Mac 작업을 가상 머신으로 옮긴다

Offscreen은 코딩 에이전트가 macOS 앱의 UI 테스트를 하거나 iOS 시뮬레이터와 GUI 앱을 실행할 때, 작업을 별도의 macOS 가상 머신에서 처리하는 도구다. 테스트 창이 사용자의 데스크톱을 차지하지 않도록 하며, 작업별 로그와 스크린샷, .xcresult 결과물을 제공한다.

Apple 실리콘 Mac과 macOS 14 이상, 전체 Xcode, Homebrew가 필요하다. 프로젝트는 현재 베타 소프트웨어로, 명령어와 설정, 디스크에 저장되는 상태가 버전별로 바뀔 수 있다. 설치와 가상 머신 이미지 준비는 다음과 같다.

brew install --cask markphelps/tap/offscreen
 # installs the CLI, the daemon, the Offscreen
 # menu bar app and Tart
open -a Offscreen # if macOS asks, allow "Offscreen Daemon" on the Local Network
offscreen image build # one-time: pulls a macOS + Xcode image, takes a while, go grab lunch

예제 프로젝트를 실행하려면 저장소를 복제한 뒤 다음 명령을 사용한다. Offscreen 자체를 빌드하는 과정은 아니다.

git clone https://github.com/markphelps/offscreen.git
cd offscreen/examples/hello
offscreen run hello test-ui

이 명령은 Mac에서 작은 SwiftUI 앱을 빌드하고, 새 가상 머신 안에서 UI 테스트를 실행한다. 같은 예제에서 offscreen run hello test-ios는 VM 내부 iOS 시뮬레이터로 테스트하고, offscreen run hello launch는 앱을 열어 스크린샷을 저장한다. 설치 방법은 설치 안내에서 확인할 수 있으며, 소스에서 빌드하는 방법도 안내한다.

저장소 루트에서 .offscreen.toml 설정을 만들고 검사한 뒤, 에이전트가 직접 xcodebuild test를 실행하는 대신 Offscreen 작업을 호출하도록 구성할 수 있다.

project = "myapp"

[prepare] # runs on your Mac before each job
run = "xcodebuild -scheme MyApp -derivedDataPath .build build"
share = [".build/Build/Products/Debug/MyApp.app"]

[tasks.ui] # runs inside the VM
lane = "vm"
run = "sh scripts/ui-test.sh"

작업 실행은 offscreen run myapp ui처럼 호출한다. 이름을 지정하지 않는 명령도 offscreen run myapp -- swift test 형식으로 VM에서 실행할 수 있다. offscreen init은 시작용 설정 파일을 만들고, offscreen check는 VM을 시작하지 않고 설정을 검사한다. offscreen run은 실행한 명령의 종료 코드를 반환하며, Offscreen 자체 오류에는 대기열 시간 초과용 75와 VM 또는 데몬 오류용 70을 쓴다. 결과물은 $OFFSCREEN_OUT에 저장되고 offscreen artifacts <job>으로 위치를 확인한다. 설정은 설정 참조, 명령과 옵션은 CLI 참조에 정리돼 있다.

Offscreen은 CLI, 작업을 실행하는 offscreend 데몬, 메뉴 막대 앱으로 구성된다. 메뉴 막대 앱을 열면 데몬이 시작되고 앱을 종료하면 데몬도 멈춘다. 여러 에이전트와 터미널, 스크립트의 작업은 하나의 대기열을 공유한다. 제작자는 이를 Apple의 한도인 macOS VM 두 대에 맞춰 제한한다고 설명한다. Tart를 VM 계층으로 사용하며, 작업마다 기준 이미지의 복제본을 만들고 작업 파일과 빌드 결과물을 옮긴 뒤 결과물을 수집하고 정리한다. 로컬에서 커밋 전에 실행하는 도구로, GitHub Actions나 Cirrus 같은 호스팅 CI를 대체하지는 않는다.

실제 하드웨어가 필요한 작업은 lane = "host"로 지정해 Mac 데스크톱에서 실행할 수 있다. 이 작업은 한 번에 하나씩, 화면이 잠기지 않고 깨어 있으며 카메라와 마이크가 꺼져 있고 사용자가 충분히 자리를 비운 경우에만 시작된다. 시작 전 취소할 수 있는 카운트다운이 표시되고, 작업 중 사용자가 돌아오면 데스크톱을 되찾을 수 있도록 알림을 보낸다. 메뉴 막대 앱은 이 작업 경로를 감시하며, 입력 모니터링 권한은 host 작업을 대기열에 넣을 때 요청한다. 사용자의 복귀를 자동 감지하는 기능은 Mac에서 직접 켜기 전까지 비활성 상태다. 활성화하기 전에 작업 경로와 안전 안내를 읽어야 한다.

추가로 데몬 동작 안내, 구조 문서, 예제 앱 안내를 제공한다. 문제가 생기면 저장소 이슈를 열 수 있다.