# Headless Mode

Run Device MCP without its window, in a terminal, so your AI agent can use your devices on a Mac nobody watches.

Device MCP can run without its window: no window, no Dock icon, no menu bar item. It runs in a terminal, and your AI agent uses your iPhone, iPad, Apple Watch, Android devices, simulators and emulators through [MCP](mcp.md), the same way it does with the window open. Your agent shows you what it sees with screenshots.

Use it on a Mac nobody looks at, such as a CI machine or a Mac mini you reach over SSH, or when you'd rather stay in the terminal.

## 1. Start Device MCP headless

Run this in a terminal (`device-mcp-cli` is Device MCP's [command line](../command-line.md)):

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

Device MCP starts right there and prints what happens: devices as they connect, each action your agent takes, and anything that needs you. Press **Control-C** to quit.

To keep it running in the background, or to open it without a terminal:

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

Stop it with `device-mcp-cli app quit`.

{% hint style="info" %}
Only one Device MCP runs at a time. Quit it first if it's open with its window.
{% endhint %}

## 2. Connect your agent

Set up your agent as on the [MCP](mcp.md) page. While Device MCP runs headless, its MCP server is always on.

To let your agent start Device MCP headless by itself when it needs a device, add `--headless` at the end of the setup command:

```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. See what your agent sees

There's no window to watch, so your agent is your eyes. It knows when Device MCP runs headless and shows you screenshots of the steps that matter. Ask for more any time: "show me the screen". It can also save screenshots and recordings to your Mac.

Your agent can do everything you'd do in the window: change Device MCP's settings, start and manage simulators and emulators, build your projects, manage the license and export diagnostics. Software updates and Factory Reset stay in the window.

## 4. Approvals and Human Handoff

[Approvals](approvals.md) and [Human Handoff](human-handoff.md) still ask you. They come as macOS notifications with their buttons, and in the terminal Device MCP runs in, where you can type:

| Type | What it does |
| --- | --- |
| `y` | **Allow Once** |
| `a` | **Always Allow** |
| `n` | **Deny** |
| `done` | You've finished on the device (Face ID, a passcode…). |
| `status` | Device MCP's MCP server, license and devices. |
| `quit` | Quits Device MCP. |

On a Mac nobody watches, allow the actions your agent needs for that run:

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

{% hint style="warning" %}
`--allow` lets your agent install apps, build and run, open links and use the clipboard without asking, until Device MCP quits. Unpairing a device and removing the license always ask.
{% endhint %}

## 5. Options

| Option | What it does |
| --- | --- |
| `--allow <actions>` | Runs these actions without asking, for this run: `all`, or names separated by commas. |
| `--port <port>` | The MCP server's port for this run. |
| `--json` | Prints one JSON object per line, for scripts. |
| `--verbose` | Also prints Device MCP's log. |
