DarwinRelay

MCP 에이전트를 위한 네이티브 macOS 실행 런타임: 셸, PTY, 백그라운드 Chrome, 접근성 기반 데스크톱 제어.

DarwinRelay는 MCP 클라이언트를 현재 사용 중인 Mac에 연결합니다. 클라이언트와 macOS 사이에 또 다른 모델 루프를 끼워 넣지 않고 구조화된 로컬 머신 기능(제한 없는 셸/파일시스템 접근, 대화형 PTY, 장기 실행 작업, 저장된 Codex 기록, 관리형 백그라운드 Chrome 작업 공간, Accessibility, ScreenCaptureKit, Vision 및 CoreGraphics를 통한 네이티브 데스크톱 제어)을 노출합니다.

[!CAUTION] DarwinRelay는 의도적으로 강력합니다. 샌드박스가 아니며 파일시스템이나 셸 명령어 허용 목록을 구현하지 않습니다. 연결된 클라이언트는 브리지를 실행 중인 macOS 사용자의 유효 권한으로 작동할 수 있습니다. localhost 너머로 노출하기 전에 SECURITY.md를 읽으십시오.

DarwinRelay를 사용하는 이유

많은 MCP 서버는 하나의 좁은 API만 노출합니다. DarwinRelay는 유용한 상태가 이미 Mac에 존재하는 개발자 및 컴퓨터 사용 워크플로우를 위한 로컬 실행 런타임으로 설계되었습니다:

• 셸 및 파일 — 명령 실행, 파일 검사 또는 수정, 패치 적용, 로컬 프로세스 관리.

• 실제 PTY — 대화형 셸, REPL, SSH, sudo 프롬프트, TUI 및 장기 실행 터미널 프로그램.

• 네이티브 컴퓨터 사용 — 의미론적 AX 쿼리/작업, 창, 대화상자, 열기/저장 패널, 키보드/마우스 폴백, 스크린샷, OCR 및 시각적 대기.

• 백그라운드 브라우저 자동화 — 포커스를 자주 빼앗지 않으면서 탐색, 검사, 입력 및 클릭이 가능한 전용 Chrome 확장 프로그램 소유 탭 풀.

• Codex 기록 — 새 모델 턴을 시작하지 않고 저장된 Codex 스레드 읽기.

• 원격 MCP 전송 — 로컬에서는 stdio, 또는 귀하가 제어하는 터널 뒤의 인증된 HTTP/OAuth 프런트 엔드.

• 실패 시 잠금 수명 주기 — 명시적 전체 액세스 잠금 해제, 감사 로깅, 프로세스 회수, 단일 인스턴스 메뉴 소유권 및 롤백 인식 앱 업데이트.

Related MCP server: mcp-server-macos-use

아키텍처

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

네이티브 데스크톱 도우미는 권한 있는 데몬이 아닌 의도적으로 수명이 짧습니다. 메뉴 앱, MacUIHelper 및 가상 커서는 안정적인 코드 서명 식별자를 사용하므로 영구 서명 ID를 사용할 수 있을 때 macOS TCC 권한이 정상적인 재빌드 후에도 유지될 수 있습니다.

요구 사항

• macOS 13 이상

• Node.js 18 이상 (CI에서는 Node.js 22 사용)

• 네이티브 데스크톱 제어 및 메뉴 앱용 Xcode 명령줄 도구 / swiftc

• 네이티브 컴퓨터 사용을 위한 손쉬운 사용 및 화면 기록 권한

• 관리되는 chrome_* 백그라운드 작업 공간을 원하는 경우에만 Google Chrome

• HTTP 전송을 원격으로 노출하는 경우에만 cloudflared 또는 기타 HTTPS 터널

• codex_thread_* 기록 도구를 원하는 경우에만 Codex CLI

빠른 시작

저장소를 복제하고 메뉴 앱을 빌드합니다:

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

앱이 macOS 메뉴 막대에 DR로 나타납니다. 요청된 데스크톱 권한을 부여한 다음 구성한 HTTP/터널 경로에 시작을 사용합니다.

소스 전용 로컬 MCP 사용의 경우 브리지를 직접 실행할 수도 있습니다. 전체 액세스는 명시적으로 확인해야 합니다:

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

기본 런타임 상태는 다음 위치에 있습니다:

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

DARWINRELAY_DATA_DIR, DARWINRELAY_LOG_DIR, DARWINRELAY_SHELL, DARWINRELAY_AUDIT_MODE와 같은 환경 변수를 사용하여 개발/테스트 인스턴스를 격리합니다.

AI 및 코딩 에이전트를 위한 안내

이 저장소에는 의도적으로 에이전트 지향 문서가 포함되어 있습니다. 저장소를 Codex, Claude, ChatGPT 또는 다른 코딩 에이전트에 제공하는 경우 AGENTS.md를 먼저 가리키십시오. 해당 파일에는 저장소 맵, 불변 조건, 개발 명령, 테스트 기대치, 서명/브라우저 규칙 및 릴리스 제약 조건이 설명되어 있습니다.

소스를 수정하지 않고 이미 설치된 DarwinRelay 런타임을 작동하는 에이전트의 경우 docs/AGENT_OPERATIONS.md 를 사용하십시오. 여기에는 전체 도구 모음 맵, 권장 결정 순서, 일반적인 오류 상태 및 안전한 런타임 워크플로우가 포함되어 있습니다. docs/ARCHITECTURE.md 는 더 깊은 추론을 위한 구성 요소/데이터 흐름 및 신뢰 경계를 설명합니다.

네이티브 데스크톱 제어

DarwinRelay는 의미론적 접근성 작업을 선호하며 시각적/원시 입력을 폴백으로 사용합니다. 핵심 기능은 다음과 같습니다:

• ui_observe, ui_tree, ui_ax_query, ui_ax_at

• 만료 참조 감지 기능이 있는 지문 기반 AX 참조

• ui_action, ui_wait_for, ui_assert

• ui_app_*, ui_window_*, 대화상자 및 파일 패널

• ScreenCaptureKit 스크린샷 및 Vision OCR

• macOS가 지원하는 곳에서는 의미론적 검증 및 제한된 포그라운드 폴백이 있는 백그라운드 PID 대상 입력

• 결정적 다단계 네이티브 버스트를 위한 ui_sequence

• 물리적 포인터를 움직이지 않는 클릭 통과 가상 AI 커서

제어 모델 및 제한 사항은 docs/DESKTOP_CONTROL.md를 참조하십시오.

백그라운드 Chrome 작업 공간

DarwinRelay는 압축되지 않은 Chrome 확장 프로그램과 네이티브 메시징을 사용합니다. 공개 확장 프로그램 ID는 안정적입니다. 예상 확장 프로그램 ID는 다음과 같습니다:

pfhahlehpahegefejooendokpkklgmgd

설치 프로그램은 기본적으로 DarwinRelay라는 로그아웃된 로컬 Chrome 프로필을 생성하거나 재사용합니다. 이렇게 하면 에이전트 브라우징 상태가 일반 Google 프로필과 분리됩니다:

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

기본 프로필은 다른 프로필의 브라우징 데이터를 삭제하거나 수정하지 않고 생성됩니다. DarwinRelay 프로필이 아직 없으면 설치 프로그램을 실행하기 전에 Chrome을 한 번 종료하여 Chrome이 Local State를 동시에 다시 쓰지 못하게 하십시오. 프로필이 있으면 Chrome이 열려 있는 동안에도 일반 재설치를 실행할 수 있습니다. DarwinRelay를 제거해도 브라우저 프로필 콘텐츠는 사용자 데이터이므로 해당 프로필은 의도적으로 유지됩니다.

그런 다음 선택한 프로필에서만 chrome://extensions를 열고 개발자 모드를 활성화한 다음 압축 해제된 확장 프로그램 로드를 선택하고 이 저장소의 chrome-extension/ 디렉터리를 선택합니다. 이 일회성 설정 단계를 위해 설치 프로그램에 --open을 전달할 수 있습니다.

확장 프로그램은 DR이라는 Chrome 네이티브 탭 그룹을 소유합니다. 일상적인 chrome_open 호출은 임의의 포그라운드 탭을 만드는 대신 미리 생성된 유휴 탭을 임대합니다. chrome_close는 작업 공간 탭을 풀로 반환합니다.

브라우저 보안 모델

완화된 승인이 기본값입니다. 구성된 chrome_* 작업 공간을 통한 일반 HTTP/HTTPS 작업에는 사이트별 터미널 권한이 필요하지 않습니다. 메뉴 앱에서 엄격한 승인을 활성화하면 범위가 지정된 URL 권한과 일회용 앱 범위 네이티브 변형 승인이 복원됩니다.

셸/AppleScript/JXA를 통한 직접 Chrome 자동화는 브리지에 의해 차단되어 일반 웹 작업이 관리되는 백그라운드 경로에 유지됩니다. 별도의 네이티브 ui_* 표면은 브라우저/OS 보안 표면에서 실제로 요구하는 경우 포그라운드 Chrome UI와 계속 상호 작용할 수 있습니다.

DARWINRELAY_ADVANCED_BROWSER=1 뒤에 선택적 원시 Browser Harness/CDP 어댑터가 있습니다. 기본적으로 비활성화되어 있으며 임의 CDP는 URL 범위로 건전하게 축소될 수 없기 때문에 엄격한 승인에서 실패 시 잠깁니다.

HTTP / OAuth 전송

mcp-http.mjs는 루프백에 바인딩되고 정적 베어러 토큰과 원격 MCP 클라이언트가 사용하는 OAuth 2.1 흐름으로 MCP HTTP 전송을 지원합니다. Cloudflare와 같은 터널은 HTTPS를 통해 루프백 서비스를 게시할 수 있습니다.

최소한의 로컬 프런트 엔드는 다음과 같습니다:

mkdir -p "$HOME/Library/Application Support/DarwinRelay"
openssl rand -hex 32 > "$HOME/Library/Application Support/DarwinRelay/http-token"
chmod 600 "$HOME/Library/Application Support/DarwinRelay/http-token"

export DARWINRELAY_HTTP_TOKEN_FILE="$HOME/Library/Application Support/DarwinRelay/http-token"
node mcp-http.mjs

SECURITY.md의 원격 액세스 위협 모델을 읽지 않고 HTTP 엔드포인트를 노출하지 마십시오. 이 프런트 엔드에서 허용하는 자격 증명은 궁극적으로 데스크톱 사용자로 로컬 코드 실행을 허용합니다.

저장소에는 해당 전송을 선호하는 사용자를 위해 원래 프로젝트에서 상속된 OpenAI Secure MCP Tunnel 설치 프로그램도 포함되어 있습니다. DEPLOY.md를 참조하십시오.

개발

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

공개 CI는 불투명한 단일 test 작업 대신 별도의 검사를 의도적으로 노출합니다:

• 정적 검사 — 구문/네이티브 빌드 검증 및 전체 기록 gitleaks 스캔

• 핵심 및 프로토콜 테스트 — MCP, HTTP/OAuth, PTY, 페더레이션, 브라우저 및 적대적 테스트

• 데스크톱 제어 테스트 — 결정적 데스크톱 프로토콜 테스트 및 네이티브 픽스처 컴파일

• 설치 및 수명 주기 테스트 — 설치 프로그램, 자동 시작, 단일 인스턴스 소유권, 롤백 및 제거 동작

실제 변경 가능한 AppKit E2E는 로그인된 Mac과 TCC 권한이 필요하므로 일회용 GitHub 호스팅 GUI 세션에서는 안정적이지 않습니다. 유지 관리자는 다음을 사용하여 로컬에서 실행할 수 있습니다:

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 참조하십시오.

보안

중요한 경계는 간단합니다: DarwinRelay는 실행 중인 macOS 계정의 권한을 가집니다. 잠금 해제 파일, 엄격한 승인, 감사 메타데이터, OAuth, 백그라운드 브라우저 라우팅 및 프로세스 회수와 같은 보안 기능은 우발적이거나 원격적인 오용을 줄입니다. 임의의 셸 액세스를 샌드박스로 바꾸지는 않습니다.

보안 보고서는 공개 이슈 대신 GitHub의 비공개 취약성 보고를 사용해야 합니다. SECURITY.md를 참조하십시오.

프로젝트 계보

DarwinRelay는 독립적으로 유지 관리되며 Alexander Rådahl Benz의 Mac Developer Bridge에서 상당히 분기되었습니다. 상속된 업스트림 기록은 의도적으로 보존되며 원본 MIT 저작권 표시는 LICENSE에 유지됩니다. 정확한 계보 및 귀속 정책은 UPSTREAM.md를 참조하십시오.

공개 dcierra/darwinrelay 저장소가 표준 개발 소스입니다. 이전 비공개 저장소는 설치된 0.5.x 런타임이 마이그레이션될 때까지 임시 레거시 프로덕션/롤백 계보로만 유지됩니다. 두 번째 활성 개발 분기가 아닙니다. 커밋 기록 매핑 및 향후 워크플로우는 docs/DEVELOPMENT_MODEL.md를 참조하십시오.

DarwinRelay는 OpenAI, Apple, Google, Cloudflare 또는 업스트림 유지 관리자와 제휜하거나 보증하지 않습니다.

라이선스

MIT. LICENSE 및 UPSTREAM.md를 참조하십시오.