읽는 데 7분
에이전트에게 맥 한 대를 따로 주는 terminal-mac, 코드와 이슈로 본 지금 상태
내 작업 화면을 직접 조작하는 에이전트를 쓰면, 작업 중인 마우스나 클립보드와 충돌할 수 있어요. terminal-mac은 에이전트가 조작할 가상 맥을 한 대 더 띄워서 이 문제를 풀어요. 그런데 제작자의 검증 문서에는 2026년 11월 9일 기준으로 "깨끗한 맥에서 실제 게스트를 띄워 조작하는 수용시험은 아직 끝나지 않았다"고 적혀 있어요.
기본 정보부터요. 제작자는 GitHub 사용자 govijr, 저장소는 2026-11-03에 만들어졌고 최신 릴리스는 같은 날 나온 v0.2.0-6이에요. 라이선스는 MIT, 실행 환경은 macOS 14 이상의 Apple silicon 맥이에요.
어떻게 움직이나
구조는 세 조각이에요.
- 호스트(내 맥)가 Apple의 Virtualization 프레임워크로 진짜 macOS 게스트를 띄워요. 게스트는 앱, 파일, 계정이 따로인 별개의 맥이에요.
- 게스트 안에서 도우미 앱(TerminalMacGuest)이 화면을 찍고 입력 이벤트를 보내요.
- 호스트 쪽 터미널 뷰어가 그 화면을 Ghostty, Kitty, iTerm2의 그림 출력 기능으로 보여 줘요. 다른 터미널에서는 가상 맥의 기본 창을 써요.
README에는 실제 화면 캡처나 데모 영상이 없어요. 위 그림은 README와 코드로 확인한 구성만 그린 거예요.
에이전트는 MCP 도구(screenshot, click, type, key 등)로 2번 도우미에게 일을 시켜요. MCP는 AI 도구가 외부 프로그램을 부르는 공통 규격이에요. Claude Code에는 플러그인 한 줄로, Cursor나 Codex 같은 다른 클라이언트에는 설정 출력을 붙여 넣는 방식으로 연결해요.
코드에서 확인한 격리 경계
README의 "에이전트는 내 데스크톱을 건드리지 않는다"는 말이 코드에서 어떻게 지켜지는지 네 곳을 읽어 봤어요(실행은 하지 않았어요).
| README의 주장 | 코드에서 본 것 |
|---|---|
| 도우미는 가상 맥에서만 돈다 | hw.model 값이 VirtualMac으로 시작하지 않으면 오류를 내고 멈춰요 |
| 게스트가 보는 공유 폴더는 둘뿐 | control(읽기·쓰기)과 tools(읽기 전용) 두 개만 연결해요 |
| 글자 입력이 클립보드를 바꾸지 않는다 | 붙여넣기 대신 유니코드 키 이벤트로 UTF-16 16단위씩 나눠 보내요. 한 번에 최대 32KiB예요 |
| 기본 네트워크는 NAT(호스트를 거쳐 외부망에 연결) | --offline이 아니면 NAT 네트워크 장치를 붙여요 |
주장과 코드는 맞았어요. 다만 README도 스스로 밝히듯 hw.model 검사는 실수로 호스트에서 도는 걸 막는 장치예요. 악성 코드를 가두는 보안 경계는 아니에요. NAT라서 게스트가 호스트나 사내망 서비스에 닿을 수도 있어요.
실행 보고와 코드 분석에서 나온 이슈
제작자의 검증 문서(VALIDATION.md)는 빌드, 서명, 설치 스크립트, 14개 단위 테스트까지만 통과했다고 적어요. 복원 이미지 내려받기, VM 설치, 부팅은 하지 않았다고 분명히 써 뒀어요. 그 빈칸은 이슈 게시판이 채우고 있어요. 11월 9일 기준 이슈와 PR은 19건, 그중 12건이 열려 있어요.
- macOS 27.2 게스트에서 권한을 다 줬는데
screenshot이 "No guest display"로 실패한다는 보고(#6). 같은 보고자는 디스크 32GiB로는 도우미 설치 공간이 모자랐다고 적었어요. - 무거운 앱을 띄우면 도우미가 "로그인 안 됨"이라고 잘못 답하고 응답을 멈춘다는 보고(#19).
- macOS 27 호스트·게스트에서 수식키가 클릭에 남는 문제 등 다섯 가지를 고친 PR(#16). 작성자는 한중일 문자 입력을 포함해 게스트에서 직접 확인했다고 적었어요.
- 게스트가 보낸 오류 문구가 이스케이프 없이 호스트 터미널에 찍힌다는 정적 분석 보고(#9, #12), 압축된 화면 프레임을 풀 때 메모리 사용 상한이 부족하다는 보고(#10). 셋 다 열려 있어요.
국내 환경에서 걸리는 지점
한글 문자열을 보내는 type 명령은 게스트 입력기에서 자모를 조합하는 방식이 아니에요. 완성된 글자를 유니코드 이벤트로 바로 보내요. 위 PR 작성자도 한중일 문자 입력을 확인했다고 적었어요. 반면 key 명령은 미국 배열 키 코드 표를 사용해요. 제가 읽은 이슈에서는 게스트 입력 소스가 한글일 때 단축키가 어떻게 동작하는지 확인할 수 없었어요.
Clash Verge·Surge·sing-box 같은 VPN·프록시 앱이 맥 전체의 트래픽을 가로채는 TUN 모드를 쓴다면 주의하세요. PR #17 작성자는 이 환경에서 가상 맥이 도메인 이름을 IP 주소로 바꾸는 DNS 요청에 응답을 받지 못한다고 보고했어요. 아직 병합되지 않았어요.
비슷한 도구와 비교
같은 Apple Virtualization 위에서 맥 VM을 다루는 도구로 cua 프로젝트의 Lume이 있어요. 둘 다 MIT예요.
| terminal-mac | Lume (cua) | |
|---|---|---|
| 첫 설정 | 게스트 설치 마법사와 권한 허용을 사람이 직접 | --unattended 프리셋으로 사용자 생성·SSH·자동 로그인까지 자동 |
| 화면 보기 | 터미널 안 그림 출력과 기본 창 | 기본 macOS VM 화면 지원, Recovery 제어는 VNC |
| 에이전트 연결 | MCP 서버와 스킬을 함께 제공 | cua 프레임워크의 일부 |
| 이력 | 11월 3일 저장소 생성, 커밋 18개 | 상위 cua 저장소가 2025년 1월 생성 |
terminal-mac은 터미널 뷰어와 Claude Code용 연결 플러그인을 함께 제공해요. 대신 무인 설정과 오래된 이력은 Lume 쪽에 있어요.
제 생각엔 지금은 "게스트 맥을 손으로 한 번 설정해 두고 실험해 볼 Apple silicon 사용자"에게 맞는 물건이에요. 업무 맥에서 상시로 에이전트를 돌릴 도구로 보기엔 일러요. 제작자 스스로 실기 수용시험을 마치지 않았고, 보안 관련 이슈 셋이 열려 있어요.
확인한 범위
- 기준일: 2026-11-09
- 직접 한 것: 커밋 80dc388 기준 소스 네 파일(Guest.swift, VirtualMachine.swift, Mailbox.swift, GuestCapture.swift)을 읽어 README 격리 주장과 대조, GitHub API로 생성일·릴리스·커밋 수·이슈 19건 확인, Lume README와 설정·화면·이력 비교. 근거 위치는 facts.md에 있어요.
- 읽은 것: terminal-mac README, docs/VALIDATION.md, 이슈 #6·#9·#16·#17·#19 본문, Lume README
- 확인하지 못한 것: Apple silicon 맥이 없어 설치·실행은 하지 않았어요. 한글 입력 소스 상태의 단축키 동작, 이슈 보고 내용의 재현도 확인하지 못했어요.
