> ## Content Index
> Fetch the complete content index at: https://blog.frostk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 에이전트에게 맥 한 대를 따로 주는 terminal-mac, 코드와 이슈로 본 지금 상태
- URL: https://blog.frostk.com/terminal-mac-agent-virtual-mac/
- Published: 2026-11-09T01:48:30.000Z
- Updated: 2026-11-09T08:01:00.000Z
- Description: terminal-mac은 Apple silicon 맥 안에 가상 맥을 하나 더 띄워 AI 에이전트가 그 화면만 조작하게 하는 MIT 오픈소스예요. 코드로 격리 경계를 확인했고, 제작자 검증 문서와 이슈로 아직 실제 게스트 수용시험이 끝나지 않은 상태임을 짚었어요.
- Author: Cat
- Tags: IT, AI, 오픈소스

내 작업 화면을 직접 조작하는 에이전트를 쓰면, 작업 중인 마우스나 클립보드와 충돌할 수 있어요. terminal-mac은 에이전트가 조작할 **가상 맥을 한 대 더 띄워서** 이 문제를 풀어요. 그런데 제작자의 검증 문서에는 2026년 11월 9일 기준으로 "깨끗한 맥에서 실제 게스트를 띄워 조작하는 수용시험은 아직 끝나지 않았다"고 적혀 있어요.

기본 정보부터요. 제작자는 GitHub 사용자 govijr, 저장소는 2026-11-03에 만들어졌고 최신 릴리스는 같은 날 나온 v0.2.0-6이에요. 라이선스는 MIT, 실행 환경은 macOS 14 이상의 Apple silicon 맥이에요.

## 어떻게 움직이나

구조는 세 조각이에요.

1. 호스트(내 맥)가 Apple의 Virtualization 프레임워크로 진짜 macOS 게스트를 띄워요. 게스트는 앱, 파일, 계정이 따로인 별개의 맥이에요.
2. 게스트 안에서 도우미 앱(TerminalMacGuest)이 화면을 찍고 입력 이벤트를 보내요.
3. 호스트 쪽 터미널 뷰어가 그 화면을 Ghostty, Kitty, iTerm2의 그림 출력 기능으로 보여 줘요. 다른 터미널에서는 가상 맥의 기본 창을 써요.

![위층은 에이전트와 터미널 뷰어, 가운데는 control(읽기·쓰기)과 tools(읽기 전용) 두 공유 폴더, 아래는 가상 맥 안의 게스트 도우미. 호스트는 파일 우편함으로 요청하고, 호스트에서 게스트에 연결하는 공유 폴더는 control과 tools 두 개예요.](https://blog.frostk.com/content/images/2026/11/hf-54896947.png)

입력은 내 맥이 아니라 가상 맥 안에서 일어나요.

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 맥이 없어 설치·실행은 하지 않았어요. 한글 입력 소스 상태의 단축키 동작, 이슈 보고 내용의 재현도 확인하지 못했어요.

## 출처

[https://github.com/govijr/terminal-macgithub.com](https://github.com/govijr/terminal-mac?ref=blog.frostk.com)

[https://github.com/govijr/terminal-mac/blob/main/docs/VALIDATION.mdgithub.com](https://github.com/govijr/terminal-mac/blob/main/docs/VALIDATION.md?ref=blog.frostk.com)

[https://github.com/trycua/cua/blob/main/libs/lume/README.mdgithub.com](https://github.com/trycua/cua/blob/main/libs/lume/README.md?ref=blog.frostk.com)