TL;DR

serve-sim은 simctl io로 시뮬레이터 프레임버퍼를 캡처하고 호스트-사이드 Swift 헬퍼가 이를 MJPEG 스트림과 WebSocket 제어 채널로 노출해 브라우저에서 60FPS 미리보기와 실시간 입력을 제공하는 도구이다. 카메라 주입은 호스트가 BGRA 프레임을 POSIX 공유 메모리에 기록하고 DYLD_INSERT_LIBRARIES로 삽입된 라이브러리가 AVFoundation 호출을 스위즐해 앱이 그 프레임을 읽도록 구현되어 파일·웹캠·플레이스홀더를 동적으로 교체할 수 있다. Connect 스타일 미들웨어를 통해 기존 개발 서버에 통합하거나 Agent Skill로 AI 에이전트와 연동할 수 있으며 설치 조건으로는 macOS, Xcode CLI, Node 20+, Apple Silicon이 요구된다.

주요 기능

• 60FPS 브라우저 스트림을 제공해 원격 환경에서 실시간 화면을 확인할 수 있다.
• 터치 제스처와 하드웨어 버튼, 키보드 단축키를 WebSocket 제어 채널로 시뮬레이터에 전달해 원격 입력을 수행한다.
• 시뮬레이터 로그를 브라우저로 포워딩해 외부 도구가 이벤트를 읽고 파이프라인에 연결할 수 있게 한다.
• 호스트-사이드 헬퍼와 DYLD_INSERT_LIBRARIES 기반의 라이브러리로 앱에 카메라 피드를 주입해 파일·웹캠·플레이스홀더를 사용하게 한다.
• Connect 스타일 미들웨어로 기존 개발 서버(Metro, Vite, Express 등)에 미리보기 UI와 상태 API를 통합한다.

어떻게 동작하는가

serve-sim은 각 부트된 iOS Simulator 옆에 작은 Swift 헬퍼 바이너리(bin/serve-sim-bin)를 실행해 simctl io로 프레임버퍼를 캡처한다. 헬퍼는 캡처한 프레임을 MJPEG 스트림으로 변환해 HTTP로 제공하고 제어는 WebSocket 채널을 통해 전달하며 헬퍼 상태는 $TMPDIR/serve-sim/의 상태 파일에 기록된다. 카메라 주입은 호스트 헬퍼가 BGRA 프레임을 POSIX 공유 메모리에 쓰고 DYLD_INSERT_LIBRARIES로 삽입된 dylib가 AVFoundation 호출을 스위즐해 그 데이터를 앱이 읽도록 하는 방식으로 구현된다.

해결 문제

호스트된 iOS 시뮬레이터를 원격으로 노출할 때 발생하는 접근성과 반복 테스트의 불편함을 줄인다. 이 도구는 로컬에서 같은 인터페이스를 띄워 사전 검증을 가능하게 하고 터널링을 통해 원격 Mac에 호스팅된 시뮬레이터를 브라우저로 안전하게 전달한다. 또한 별도 Xcode 플러그인이나 앱 내 계측 없이 화면 스트리밍과 입력 전달, 카메라 주입을 통합해 개발·디버그 워크플로를 단순화한다.

차별점

• 별도의 Xcode 플러그인이나 앱 인스트루먼테이션 없이 simctl을 통해 직접 프레임버퍼를 캡처하는 아키텍처를 사용한다.
• 호스트-사이드의 작은 Swift 헬퍼 바이너리를 포함해 설치만으로 동작하며, 헬퍼가 per-device로 동작해 여러 시뮬레이터를 동시에 지원한다.
• 미들웨어 형태로 기존 개발 서버에 쉽게 통합할 수 있고 proxyHelpers 옵션으로 단일 포트 뒤에서도 WebSocket 업그레이드를 라우트해 원격 접근을 단순화한다.

사용 사례

• 원격으로 호스팅된 시뮬레이터를 브라우저로 노출해 QA 엔지니어와 협업자가 별도 Mac 없이 앱 UI를 확인하고 제스처를 전송하는 용도로 사용된다.
• AI 코딩 에이전트(Claude Code, Cursor, Codex 등)의 스킬로 통합되어 에이전트가 시뮬레이터를 조작하고 화면을 캡처해 자동화된 리팩터링이나 디버깅 워크플로에 활용된다.
• 로컬 개발 서버(Metro 등)에 미들웨어로 임베드해 Expo 등의 개발 환경에서 시뮬레이터 미리보기를 자동으로 시작하고 디버그 세션을 단축하는 데 사용된다.

시작하기

시작하려면 macOS와 Xcode command line tools가 설치되어 있어야 하며 Node의 유지관리되는 LTS(현재 Node 20+)가 필요하다. Apple Silicon(arm64) 전용으로 제공되는 바이너리를 사용하므로 Intel(x86_64) Mac에서는 실행되지 않는다. 간단한 실행은 npx serve-sim으로 서버를 띄운 뒤 브라우저에서 http://localhost:3200에 접속하는 방식이며, 개발용 빌드는 제공된 bun 명령으로 JS 번들과 Swift 헬퍼를 각각 빌드할 수 있다.

요구사항

• macOS에 Xcode command line tools(xcrun simctl) 설치
• Node.js 유지관리 LTS 릴리스(문서 기준 현재 Node 20 이상)
• Apple Silicon (arm64) 아키텍처; Intel(x86_64)에서는 번들된 헬퍼가 실행되지 않음
• 카메라 인젝션 기능을 사용하려면 macOS 14 이상에서 동작하는 호스트 헬퍼