serve-sim 사용법, iOS 시뮬레이터를 브라우저로 스트리밍하기
serve-sim은 실행 중인 iOS 시뮬레이터를 브라우저로 중계하는 명령줄 도구다. npx serve-sim 한 줄로 localhost:3200에서 60FPS 스트림을 보고, Codex·Cursor·Claude 같은 AI 에이전트와 연동한다.
목차
serve-sim은 macOS에서 실행 중인 iOS 시뮬레이터를 브라우저 탭으로 열어 주는 명령줄 도구다. 시뮬레이터를 부팅한 상태에서 npx serve-sim 한 줄만 실행하면 http://localhost:3200 주소에서 화면을 영상으로 보고 마우스와 키보드로 그대로 조작할 수 있다. Expo 개발자 Evan Bacon이 공개한 오픈소스이며, 2026년 7월 기준 공식 GitHub 저장소(EvanBacon/serve-sim) README를 근거로 정리했다. 실행에는 Apple Silicon 맥과 Node.js 20 이상, Xcode 커맨드라인 도구가 필요하다.
이 글은 macOS·Apple Silicon 환경에서 iOS 시뮬레이터를 쓰는 개발자를 대상으로 하며, 안드로이드 에뮬레이터나 실제 기기 미러링은 다루지 않는다.
serve-sim은 무엇을 하는 도구인가
한마디로 실행 중인 iOS 시뮬레이터 화면을 브라우저로 중계하는 도구다. Xcode를 열고 시뮬레이터 창을 따로 띄우던 흐름을 브라우저 탭 하나로 옮겨 준다. 공식 README에 따르면 serve-sim은 시뮬레이터의 프레임버퍼를 simctl io로 캡처해 MJPEG 영상 스트림과 WebSocket 제어 채널로 노출하고, 그 위에 React로 만든 미리보기 UI를 얹는다. 여기서 프레임버퍼는 화면에 그려지는 픽셀 데이터를 뜻하고, MJPEG는 연속된 JPEG 이미지를 영상처럼 흘려보내는 방식이다.
핵심은 앱이나 Xcode를 건드리지 않는다는 점이다. 저장소 설명대로 Xcode 플러그인을 설치하거나 앱 코드에 계측 코드를 심을 필요가 없다. 이미 부팅된 시뮬레이터가 있으면 거기에 그대로 붙는다. 자세한 동작과 소스는 serve-sim 공식 GitHub 저장소에서 확인할 수 있다.
설치와 실행: npx 한 줄로 시작하기
별도 설치 과정은 없다. 시뮬레이터를 먼저 부팅해 두고 터미널에서 npx serve-sim을 실행하면, 공식 README 기준 기본 주소인 http://localhost:3200 에서 미리보기 UI가 열린다. 내부적으로 헬퍼는 3100 포트, 미리보기 서버는 3200 포트를 기본값으로 쓴다.
실행 조건은 분명하다. serve-sim README는 macOS와 Xcode 커맨드라인 도구(xcrun simctl), Node.js LTS(현재 기준 Node 20 이상)를 요구한다고 밝힌다. 한 가지 제약은 Apple Silicon 전용이라는 점이다. 저장소 설명에 따르면 함께 배포되는 serve-sim-bin 헬퍼가 arm64 바이너리라서 인텔(x86_64) 맥에서는 동작하지 않는다. 배포는 npm에 serve-sim 이름으로 올라와 있다.
# 시뮬레이터를 부팅한 뒤 실행
npx serve-sim
# 포트를 바꿔서 열기
npx serve-sim --port 4000
# 미리보기 UI 없이 스트림만 띄우기
npx serve-sim --no-preview자주 쓰는 옵션과 명령어
serve-sim은 실행 옵션과 별도의 하위 명령을 함께 제공한다. 옵션은 스트림을 어떻게 열지 정하고, 하위 명령은 실행 중인 시뮬레이터를 터미널에서 직접 조작한다. 공식 README에 정리된 주요 옵션은 다음과 같다.
| 옵션 | 하는 일 | 참고 |
|---|---|---|
| -p, --port | 시작 포트 지정 | 미리보기 3200, 헬퍼 3100 |
| --no-preview | 미리보기 UI 없이 스트림만 | |
| -d, --detach | 헬퍼만 띄우고 종료(데몬) | |
| --fit | 미리보기 창 크기에 맞춤 | |
| --theme | 열기 전 외형 지정 | light 또는 dark |
| --list / --kill | 스트림 목록 조회 / 종료 |
하위 명령으로는 button(기본값 home), type, rotate, 제스처를 주입하는 gesture, 카메라 입력을 바꾸는 camera 계열이 있다. 자동화 스크립트에서 시뮬레이터를 다룰 때 유용하다.
브라우저에서 시뮬레이터를 어떻게 조작하나
마우스와 키보드로 그대로 조작한다. 클릭이 탭, 드래그가 스와이프로 이어지고, README에 따르면 Option 키를 누른 채 조작하면 멀티터치 제스처가 된다. 이미지나 영상 파일을 브라우저 화면으로 끌어다 놓으면 기기에 추가돼 사진 선택 같은 테스트를 쉽게 만든다. 홈으로 돌아갈 때는 CMD+SHIFT+H 단축키를 쓴다.
화면 스트림은 공식 README 기준 최대 60FPS로 흐른다. 시뮬레이터 로그도 브라우저로 전달되므로 화면과 로그를 한자리에서 보며 디버깅할 수 있다. 같은 동작을 터미널에서 직접 넣고 싶다면 하위 명령을 쓴다.
# 홈 버튼 누르기(기본값)
npx serve-sim button
# 텍스트 입력
npx serve-sim type "[email protected]"
# 실행 중인 스트림 목록과 종료
npx serve-sim --list
npx serve-sim --kill
AI 코딩 에이전트·개발 서버와 연동하기
serve-sim이 겨냥하는 핵심 쓰임새가 여기에 있다. 공식 README는 이 도구가 Codex, Cursor, Claude Desktop 같은 에이전트 도구와 함께 쓰이도록 설계됐다고 설명한다. 로컬에서 열거나, LAN으로 공유하거나, 원격 맥에 띄운 뒤 터널로 연결하는 방식도 가능하다. 로그가 브라우저로 전달되므로 화면을 읽는 에이전트가 시뮬레이터 상태를 함께 파악한다. 제작자 Evan Bacon은 2026년 5월 X 공지에서 이제 어떤 iOS 앱이든 Codex나 브라우저에서 직접 'inspect element'를 할 수 있다고 소개했다(기여자 @rounak의 작업). 웹 개발자가 브라우저 개발자도구로 요소를 검사하듯, 에이전트가 네이티브 iOS 앱 화면을 들여다보며 조작할 수 있다는 뜻이다.
저장소에는 skills/serve-sim/ 경로에 에이전트 스킬이 함께 들어 있어 탭·제스처·회전·카메라 주입 같은 조작을 AI 코딩 에이전트에게 가르친다. 스킬을 폴더 하나로 구성하는 방식이 궁금하다면 SKILL.md 폴더로 에이전트 스킬을 시작하는 방법을 함께 보면 감이 잡힌다. 이미 쓰는 개발 서버가 있다면 미들웨어로 끼워 넣을 수도 있다. Metro, Vite, Next, Express 같은 서버에 다음처럼 붙인다.
import { simMiddleware } from "serve-sim/middleware";
app.use(simMiddleware({ basePath: "/.sim" }));명령줄 도구로 AI 에이전트의 손발을 넓히는 흐름이 낯설다면, 같은 결의 다른 사례로 OfficeCLI를 AI 에이전트와 연동하는 방법도 참고할 만하다.