terminal-mac은 애플 Virtualization 프레임워크로 진짜 macOS 가상 머신을 띄우고, 그 화면을 터미널 안에 그려 주는 오픈소스입니다. AI 에이전트는 MCP 도구로 이 가상 Mac만 조작하고 사용자의 실제 Mac은 건드리지 않습니다. 다만 아직 초기 릴리스 후보이고, 개발자 본인의 Claude 시연에서도 글자 입력 오류가 드러났습니다.
컴퓨터 사용(computer use) 에이전트가 실제 데스크톱을 쓰는 동안 사람은 컴퓨터를 비워 줘야 합니다. 11월 3일 GitHub에 공개된 terminal-mac은 이 문제를 “에이전트에게 따로 Mac을 한 대 주는” 방식으로 풉니다. 저장소 설명은 “Entire MacOS running in your terminal”, 라이선스는 MIT이고, 공개 이틀 만인 11월 5일 새벽(한국 시각) 기준 GitHub 스타 약 1,130개, 포크 75개를 모았습니다.
README, Swift 소스 코드, 개발자의 X 시연 영상을 직접 확인해 구조와 한계를 정리합니다.
동작 원리: 진짜 macOS 가상 머신 + 게스트 안의 도우미 앱
terminal-mac은 에뮬레이터가 아닙니다. 애플이 macOS에 기본으로 넣은 Virtualization 프레임워크로 macOS 게스트를 설치·부팅합니다. 설치 이미지는 프레임워크의 VZMacOSRestoreImage.latestSupported가 알려 주는 애플 공식 복원 이미지(IPSW)를 애플 서버에서 직접 내려받아 씁니다. 저장소가 macOS 이미지를 배포하지는 않습니다.
화면과 입력은 게스트 안에서 처리합니다. 가상 Mac에 설치하는 도우미 앱(TerminalMacGuest.app)이 ScreenCaptureKit으로 게스트 화면을 캡처하고, CGEvent로 마우스·키보드 이벤트를 게스트 안에 넣습니다. 호스트와 도우미는 네트워크가 아니라 virtio-fs 공유 폴더 안의 JSON 요청·응답 파일로 통신합니다. 그래서 실제 Mac의 포인터와 클립보드는 건드리지 않는다는 것이 개발자의 설명입니다.
터미널 표시는 Kitty 그래픽 프로토콜(Kitty·Ghostty)과 iTerm2 인라인 이미지 방식을 씁니다. 화면이 바뀔 때만 최대 초당 30프레임을 무손실 lz4 압축 픽셀로 보내고, Kitty·Ghostty에서는 공유 메모리로 전달합니다. 그 밖의 터미널에서는 일반 VM 창이 열립니다.
| 항목 | 내용(README·코드 기준) |
|---|---|
| 호스트 | Apple Silicon Mac, macOS 14 이상 |
| 언어·버전 | Swift, v0.2.0 build 6(2026-11-03), 자체 서명·애플 공증 없음 |
| 기본 자원 | 메모리 4GiB, CPU는 호스트 코어 절반과 4개 중 작은 값, 디스크 64GiB(sparse) |
| 화면 | 1280×800 포인트, 2배 HiDPI(2560×1600 픽셀) |
| 뷰어 터미널 | Ghostty, Kitty, iTerm2(tmux 미지원) |
| 첫 실행 | 인터넷으로 수 GB의 macOS 복원 이미지 다운로드, 게스트 초기 설정은 사람이 직접 |
개발자는 X 답글에서 macOS 설치에 약 18GB가 필요하고, M4 Pro(메모리 24GB)에서 돌렸다고 밝혔습니다.
에이전트 도구: MCP 8개, CLI, 스킬
설치와 Claude Code 연결은 README의 다음 명령으로 합니다.
curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash/plugin install terminal-mac --marketplace govijr/terminal-macclaude mcp add terminal-mac -- terminal-mac mcp
terminal-mac skills install # → ~/.claude/skills/terminal-mac/SKILL.mdMCP 서버(stdio)가 제공하는 도구는 코드 기준 screenshot, click, move, drag, scroll, type, key, status 8개입니다. README 본문은 move를 빼고 7개로 적었습니다. 좌표는 마지막 스크린샷의 왼쪽 위 기준 픽셀입니다. 스킬은 “보고, 행동하고, 다시 확인하는” 순서와 로그인·권한 창이 뜨면 사람에게 넘기라는 규칙을 담았고, MCP가 없는 에이전트는 CLI를 씁니다.
./dist/terminal-mac action default screenshot --output /tmp/guest.png
./dist/terminal-mac action default click 640 400
./dist/terminal-mac action default type 'Hello from the agent'
./dist/terminal-mac action default key cmd+space
알려진 것과 다른 점과 한계
1. 개발자 시연에서도 글자 입력이 실패했습니다
개발자는 발표 직후 “Claude가 terminal-mac을 쓰는 시연” 영상(약 89초)을 따로 올렸습니다. Claude Code(Opus 5.5)가 Freeform에 “Claude Code → terminal-mac → macOS VM” 도식을 그리는 작업을 6분 27초 만에 끝냅니다. 그런데 Claude의 마지막 보고에는 “type 동작이 Spotlight와 Freeform에서 글자를 하나도 입력하지 못해 한 글자씩 키로 쳤다”, “드래그는 가끔만 됐고 메뉴 항목 클릭은 먹히지 않아 방향키와 키보드 메뉴 탐색으로 우회했다”는 내용이 있습니다. 현재 공개 코드에서 type 처리 부분은 첫 공개 이후 바뀌지 않았습니다.
2. 실제 게스트 검증은 문서상 미완료입니다
README는 “깨끗한 Mac에서의 실제 게스트 검증이 아직 남았다”고 적고, docs/VALIDATION.md도 자동 테스트는 통신 규약 점검일 뿐 게스트 설치·조작 성공의 증거가 아니라고 구분합니다. 11월 4일에는 macOS 27.2에서 도우미 앱이 재실행을 반복한다는 이슈(#1)도 열렸습니다.
3. 아직 없는 기능
VM 복제, 되돌리기 체크포인트, 접근성 트리 스냅샷(snapshot은 스크린샷의 다른 이름), 무인 게스트 설정, VM 삭제 명령이 없습니다. 셸 명령 실행 도구도 일부러 넣지 않았습니다.
애플 라이선스: 가상 macOS는 Mac 한 대당 2개까지
macOS Tahoe 26 소프트웨어 사용권 계약 2B(iii)항은 사용자가 소유하거나 관리하는 애플 컴퓨터 한 대에서 가상 환경으로 macOS를 “최대 2개 추가로” 설치·실행하도록 허용합니다. 목적은 (a) 소프트웨어 개발, (b) 개발 중 테스트, (c) macOS Server 사용, (d) 개인적·비상업적 사용으로 한정됩니다. 또 3조(개발자 서비스 임대)의 예외를 빼면 가상 사본을 서비스 뷰로, 시분할, 터미널 공유, 중계 서비스 같은 용도로 쓸 수 없습니다.
terminal-mac은 terminal-mac up work처럼 VM을 여러 개 만들 수 있고 코드에 개수 제한은 없습니다. 개발·테스트용 에이전트 작업은 허용 목적에 가깝지만, 일반 업무 자동화나 가상 Mac을 남에게 제공하는 서비스는 조항과 충돌할 수 있어 법무 검토가 필요합니다.
보안과 운영 주의점
- 네트워크는 열려 있습니다. 기본 NAT 네트워크로 게스트가 인터넷에 나가고, 호스트나 사내망 서비스에 닿을 수도 있습니다. README는 “네트워크가 격리된, 악성 코드용으로 강화된 환경이 아니다”라고 명시합니다.
--offline을 주면 게스트 네트워크 장치가 빠집니다. - 공유 폴더는 2개뿐입니다. 읽기·쓰기가 되는
control(요청·응답과 스크린샷)과 읽기 전용tools(도우미 앱)만 연결되고, 호스트 홈 폴더·프로젝트 폴더·클립보드·마이크·카메라는 붙지 않습니다. - 호스트 실행 차단은 안전장치일 뿐입니다. 도우미는
hw.model이 VirtualMac으로 시작할 때만 돌지만, README는 이것이 하드웨어 증명이나 오염된 호스트에 대한 방어가 아니라고 밝힙니다. - 배포물은 애플 공증을 받지 않았습니다. 자체 서명이고, 설치 스크립트의 SHA-256 기대값도 같은 릴리스의 get.sh 안에 들어 있습니다.
- 권한과 계정은 사람 몫입니다. 게스트의 화면 기록·손쉬운 사용 권한은 직접 허용해야 하고, 스킬은 비밀번호·2단계 인증·결제 창에서 멈추도록 지시합니다.
어디에 쓰면 맞는가
| 도구 | 방식 | terminal-mac과의 차이 |
|---|---|---|
| Claude Code 컴퓨터 사용 | 실제 데스크톱을 앱별 승인 후 조작 | terminal-mac은 별도 VM이라 사람이 같은 Mac을 계속 씀 |
| Anthropic computer use 데모 | Docker 안 Linux 데스크톱 | terminal-mac은 macOS 앱을 다룰 수 있음 |
| voxl | 원격 화면 스트리밍 서버(조작 API 없음) | terminal-mac은 VM 생성·조작 도구까지 포함, 대신 Mac 한 대 안에서만 |
| Lume(cua) | Virtualization 프레임워크 CLI, MIT | Lume은 무인 설정 지원, terminal-mac은 터미널 화면 표시가 강점 |
| Tart | Virtualization 프레임워크, OCI 레지스트리로 VM 배포 | CI용. 저장소는 현재 openai/tart, 라이선스 FSL-1.1-ALv2 |
| UTM | QEMU 기반, macOS 게스트는 Virtualization 프레임워크 | 범용 VM 앱, 에이전트 도구 없음 |
terminal-mac은 Mac 앱 개발자가 자기 Mac에서 에이전트에게 GUI 테스트를 맡기고 터미널 옆에서 지켜볼 때 가장 잘 맞습니다. Linux 서버의 대량 운용, 강한 격리가 필요한 악성 코드 분석, 글 입력이 많은 작업에는 아직 맞지 않습니다.
반응은 X에 집중됐습니다. 개발자의 11월 3일 발표 글은 11월 5일 새벽 기준 조회 약 50만 회, 좋아요 5,528개를 기록했습니다. 반면 Hacker News 등록 글은 1점, 댓글 0개에 그쳤습니다.
자주 묻는 질문
Q. 인텔 Mac이나 Windows에서도 되나요?
A. 안 됩니다. Apple Silicon Mac과 macOS 14 이상이 필요합니다. 애플 Virtualization 프레임워크의 macOS 게스트 기능이 Apple Silicon 전용이기 때문입니다.
Q. 에이전트가 제 Mac의 파일을 볼 수 있나요?
A. 기본 설정에서는 호스트 홈 폴더와 클립보드가 연결되지 않습니다. 다만 네트워크로 호스트·사내망 서비스에 닿을 수 있어 민감한 환경에서는 --offline이 필요합니다.
Q. 회사 업무 자동화에 써도 되나요?
A. 프로그램은 MIT지만 안의 macOS는 애플 사용권 계약을 따릅니다. Mac 한 대당 2개, 개발·테스트·macOS Server·개인 비상업 용도로 한정되므로 용도를 먼저 확인해야 합니다.
출처: govijr/terminal-mac GitHub 저장소(README, docs/AGENT.md, docs/VALIDATION.md, Sources, 이슈 #1), 개발자 X 발표 글(2026-11-03), 개발자 X Claude 시연 영상, Apple macOS Tahoe 26 소프트웨어 사용권 계약, Claude Code 컴퓨터 사용 문서, Tart, cua(Lume), UTM
대표 이미지: govijr/terminal-mac 저장소 소셜 프리뷰(흑백 변환)
