# 헤드리스 모드

Device MCP를 창 없이 터미널에서 실행해, 아무도 지켜보지 않는 Mac에서도 AI 에이전트가 기기를 사용할 수 있게 합니다.

Device MCP는 창 없이 실행할 수 있습니다. 창도, Dock 아이콘도, 메뉴 막대 항목도 없습니다. 터미널에서 실행되며, AI 에이전트는 창이 열려 있을 때와 똑같이 [MCP](mcp.md)로 iPhone, iPad, Apple Watch, Android 기기, 시뮬레이터와 에뮬레이터를 사용합니다. 에이전트는 자신이 보는 화면을 스크린샷으로 보여 줍니다.

CI 머신이나 SSH로 접속하는 Mac mini처럼 아무도 보지 않는 Mac에서, 또는 터미널을 떠나고 싶지 않을 때 사용하세요.

## 1. Device MCP를 헤드리스로 시작하기
터미널에서 다음 명령을 실행하세요(`device-mcp-cli`는 Device MCP의 [명령줄 도구](../command-line.md)입니다).

```bash
device-mcp-cli headless
```

Device MCP가 그 자리에서 시작되어 일어나는 일을 출력합니다. 연결되는 기기, 에이전트가 하는 각 동작, 사용자가 처리해야 할 일이 표시됩니다. 종료하려면 **Control-C**를 누르세요.

백그라운드에서 계속 실행하거나 터미널 없이 열려면 다음 명령을 사용하세요.

```bash
device-mcp-cli headless > device-mcp.log &
device-mcp-cli app open --headless
```

`device-mcp-cli app quit`으로 종료합니다.

{% hint style="info" %}
Device MCP는 한 번에 하나만 실행할 수 있습니다. 창이 열린 상태로 실행 중이면 먼저 종료하세요.
{% endhint %}

## 2. 에이전트 연결하기
[MCP](mcp.md) 페이지에 나온 대로 에이전트를 설정하세요. Device MCP가 헤드리스로 실행되는 동안에는 MCP 서버가 항상 켜져 있습니다.

에이전트가 기기가 필요할 때 Device MCP를 직접 헤드리스로 시작하게 하려면 설정 명령 끝에 `--headless`를 추가하세요.

```bash
claude mcp add --scope user device-mcp -- "/Applications/Device MCP.app/Contents/MacOS/device-mcp" --headless
```

```bash
codex mcp add device-mcp -- "/Applications/Device MCP.app/Contents/MacOS/device-mcp" --headless
```

## 3. 에이전트가 보는 화면 확인하기
지켜볼 창이 없으니 에이전트가 사용자의 눈이 됩니다. 에이전트는 Device MCP가 헤드리스로 실행 중인지 알고, 중요한 단계마다 스크린샷을 보여 줍니다. 더 보고 싶으면 언제든 "화면 보여 줘"라고 요청하세요. 스크린샷과 화면 기록을 Mac에 저장할 수도 있습니다.

창에서 할 수 있는 일은 에이전트도 모두 할 수 있습니다. Device MCP 설정 변경, 시뮬레이터와 에뮬레이터 시작 및 관리, 프로젝트 빌드, 라이선스 관리, 진단 정보 내보내기까지 가능합니다. 소프트웨어 업데이트와 Factory Reset은 창에서만 할 수 있습니다.

## 4. 승인과 Human Handoff
[승인](approvals.md)과 [Human Handoff](human-handoff.md)는 헤드리스 모드에서도 사용자에게 묻습니다. 요청은 버튼이 있는 macOS 알림으로 오고, Device MCP가 실행 중인 터미널에도 표시됩니다. 터미널에서는 다음과 같이 입력할 수 있습니다.

| 입력 | 설명 |
| --- | --- |
| `y` | **Allow Once** |
| `a` | **Always Allow** |
| `n` | **Deny** |
| `done` | 기기에서 할 일(Face ID, 암호 입력…)을 마쳤음을 알립니다. |
| `status` | Device MCP의 MCP 서버, 라이선스, 기기 상태를 보여 줍니다. |
| `quit` | Device MCP를 종료합니다. |

아무도 지켜보지 않는 Mac에서는 이번 실행에 에이전트가 필요한 동작을 미리 허용하세요.

```bash
device-mcp-cli headless --allow all
```

{% hint style="warning" %}
`--allow`를 사용하면 Device MCP가 종료될 때까지 에이전트가 묻지 않고 앱을 설치하고, 빌드 및 실행하고, 링크를 열고, 클립보드를 사용할 수 있습니다. 기기 페어링 해제와 라이선스 제거는 항상 묻습니다.
{% endhint %}

## 5. 옵션
| 옵션 | 설명 |
| --- | --- |
| `--allow <actions>` | 이번 실행 동안 이 동작들을 묻지 않고 실행합니다. `all` 또는 쉼표로 구분한 이름을 지정합니다. |
| `--port <port>` | 이번 실행에서 사용할 MCP 서버 포트입니다. |
| `--json` | 스크립트용으로 한 줄에 JSON 객체 하나씩 출력합니다. |
| `--verbose` | Device MCP의 로그도 함께 출력합니다. |
