Setup Guide

Five steps to control any iOS app from your AI agent. Plus one optional step if you want deeper integration in your own dev app.

1. Install Haptix on your Mac

Before you install:

• Install full Xcode from the App Store or Apple Developer downloads. Command Line Tools alone are not enough; Haptix needs devicectl and xcodebuild.
• Prepare your iPhone or iPad by enabling Developer Mode and UI Automation.
• Expect a Camera permission step during setup. Haptix needs it to capture the device screen during sessions.

The haptix binary is the daemon, the MCP server, and a CLI mirror of every MCP tool. Install with the one-shot script:

curl -fsSL https://get.haptix.dev/install.sh | bash

Then run:

haptix setup

haptix setup walks through:

• macOS Camera permission — required for screen capture during sessions. Sessions refuse to start without it.
• launchd daemon — registers dev.haptix.server and starts it.

Requires macOS 15.0+ (Sequoia) and Apple Silicon. If haptix setup reports cameraPermissionDenied, open System Settings → Privacy & Security → Camera, enable Haptix (or your terminal app), then run haptix stop && haptix start.

If Xcode is installed but not selected, run:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch

2. Get a license key

Start a free trial — no signup, no credit card. One trial per machine.

haptix trial

Got a purchased key? Activate it with:

haptix license HPTX-XXXX-XXXX-XXXX

The key lives in the daemon. Your iOS app never needs to see it.

3. Prepare your iPhone or iPad

Before Haptix can control a physical iPhone or iPad (iOS 18+), enable two settings on the device. You cannot just plug in any phone and start driving it; iOS requires Developer Mode first.

Physical devices only. Haptix works with connected iPhone and iPad hardware, not the iOS Simulator.

4. Connect via USB

Connect your iPhone or iPad to your Mac with a USB cable (Lightning or USB-C). Haptix discovers USB devices automatically — no IP addresses, no Bonjour, no firewall prompts. Some charge-only cables won't work; use one that supports data.

5. Configure your AI agent

Add the Haptix MCP server to your AI agent's configuration. See the full MCP Setup page for all supported agents, or use the quick config below:

{
  "mcpServers": {
    "haptix": {
      "url": "http://localhost:4278/mcp"
    }
  }
}

This works for Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json), and Claude Desktop. For Claude Code, run:

claude mcp add --transport http haptix http://localhost:4278/mcp

You're ready. Ask your agent to start a session. It can now take fresh screenshots, tap, swipe, draw paths, type, pinch, rotate, and read the accessibility tree on any app on your device.

Optional — Add HaptixKit for deeper integration

Steps 1–5 work on any iOS app. The Haptix daemon already handles the basic device control, so no in-app changes are needed for that part.

If you want to give your agent extra context that the daemon alone can't see — your app's console output (print(), NSLog, os_log), annotation overlays drawn on the device, the activity halo, and haptic feedback — embed HaptixKit in your own app.

Add the Swift Package

In Xcode: File → Add Package Dependencies → https://github.com/haptix-dev/HaptixKit → Add Package.

Or in your Package.swift:

dependencies: [
    .package(
        url: "https://github.com/haptix-dev/HaptixKit",
        from: "1.5.0"
    )
]

Only link HaptixKit to your Debug configuration. In your target's Build Phases, set the framework to optional, or use a conditional dependency to exclude it from Release builds entirely.

Add one line to your app

#if DEBUG
import HaptixKit
#endif

@main
struct MyApp: App {
    init() {
        #if DEBUG
        Haptix.start()
        #endif
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

No license argument — the daemon already has it from haptix trial or haptix license. Wrap in #if DEBUG to exclude from production builds. App Review may reject apps that include development tools, and it would expose a remote control surface to your users.

Troubleshooting

See Troubleshooting for more.