Target Platform
- Question: "Which platform(s) do you want to automate?"
- Options: iOS only, Android only, Both iOS and Android
LLM Configuration Mode
- Question: "How do you want to configure AI/LLM?"
- Options:
  - Platform (Recommended) - Minitap handles LLM config, just need API key
  - Local - Full control with local config files and your own API keys
Device Type (if iOS selected)
- Question: "What iOS device setup do you need?"
- Options:
  - Physical device (iPhone/iPad via USB)
  - Simulator (Xcode iOS Simulator)
Device Type (if Android selected)
- Question: "What Android device setup do you need?"
- Options:
  - Physical device (via USB/WiFi ADB)
  - Cloud device (Minitap virtual Android)

Phase 2: Check Prerequisites

Run these checks based on user selections:

# Always check
python3 --version    # Requires 3.12+
which uv            # Package manager

# For iOS physical device
which idevice_id    # libimobiledevice
which appium        # Appium
appium driver list  # XCUITest driver

# For iOS simulator
which idb_companion  # Facebook idb

# For Android
which adb           # Android platform tools
adb devices         # Device connection

Phase 3: Install Missing Dependencies

iOS Physical Device Setup:

# Install libimobiledevice
brew install libimobiledevice

# Install Appium + XCUITest
npm install -g appium
appium driver install xcuitest

iOS Simulator Setup:

brew tap facebook/fb
brew install idb-companion

Android Setup:

# macOS
brew install --cask android-platform-tools

# Linux
sudo apt install android-tools-adb

UV Package Manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Phase 4: Create Project

# Create new project
uv init <project-name>
cd <project-name>

# Add SDK
uv add minitap-mobile-use python-dotenv

Phase 5: Configure Credentials

For Platform Mode:

Direct user to https://platform.minitap.ai to create account
Navigate to API Keys → Create API Key
Create .env file:

MINITAP_API_KEY=<their-key>

Add .env to .gitignore

For Local Mode:

Copy the config template:

cp llm-config.override.template.jsonc llm-config.override.jsonc

Edit llm-config.override.jsonc with preferred models (refer to llm-config.defaults.jsonc for recommended settings)
Add provider API keys to .env (OPENAI_API_KEY, etc.) or set MINITAP_API_KEY for optimized config

Phase 6: Device-Specific Setup

iOS Physical Device (requires manual Xcode steps):

Inform user they need to:

Open WebDriverAgent in Xcode:

open ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

Sign these targets with their Apple ID:
- WebDriverAgentRunner
- WebDriverAgentLib
- IntegrationApp
Change Bundle IDs to unique values
Build IntegrationApp once with device connected
Trust developer certificate on device: Settings → General → VPN & Device Management

Android Physical Device:

Inform user they need to:

Enable Developer Options (tap Build Number 7 times)
Enable USB Debugging
Connect device and tap "Allow" on USB debugging prompt

Phase 7: Create Starter Script

Generate main.py based on configuration:

Platform Mode:

import asyncio
from dotenv import load_dotenv
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import PlatformTaskRequest

load_dotenv()

async def main() -> None:
    agent = Agent()
    await agent.init()

    result = await agent.run_task(
        request=PlatformTaskRequest(task="your-task-name")
    )
    print(result)
    await agent.clean()

if __name__ == "__main__":
    asyncio.run(main())

Local Mode:

import asyncio
from dotenv import load_dotenv
from minitap.mobile_use.sdk import Agent
from minitap.mobile_use.sdk.types import AgentProfile
from minitap.mobile_use.sdk.builders import Builders

load_dotenv()

async def main() -> None:
    profile = AgentProfile(name="default", from_file="llm-config.override.jsonc")
    config = Builders.AgentConfig.with_default_profile(profile).build()

    agent = Agent(config=config)
    await agent.init()

    result = await agent.run_task(
        goal="Your automation goal here",
        name="task-name"
    )
    print(result)
    await agent.clean()

if __name__ == "__main__":
    asyncio.run(main())

Phase 8: Verify Setup

Run verification based on device type:

# iOS physical
idevice_id -l

# iOS simulator
xcrun simctl list devices

# Android
adb devices

# Test SDK import
uv run python -c "from minitap.mobile_use.sdk import Agent; print('SDK OK')"

Quick Reference

Setup Type	Key Dependencies	Verification
iOS Physical	Appium, XCUITest, libimobiledevice	`idevice_id -l`
iOS Simulator	idb-companion	`xcrun simctl list`
Android Physical	ADB	`adb devices`
Android Cloud	None (Platform only)	N/A

Troubleshooting

Issue	Solution
Python < 3.12	Install Python 3.12+ via pyenv or homebrew
UV not found	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
idevice_id not found	`brew install libimobiledevice`
ADB not found	`brew install --cask android-platform-tools`
WDA build fails	Check Xcode signing for all 3 targets
Device unauthorized	Enable USB debugging, tap Allow on device
CLT version error	`sudo xcode-select --install`

Examples

Example 1: New iOS automation project

User: "Help me set up mobile automation for my iOS app"
→ Ask: Platform preference (iOS), Mode (Platform), Device (Physical)
→ Check: python3, uv, libimobiledevice, appium
→ Install: Missing dependencies
→ Create: Project with uv init
→ Configure: .env with MINITAP_API_KEY
→ Guide: Xcode WebDriverAgent signing
→ Verify: idevice_id -l shows device

Example 2: Android cloud setup

User: "Set up mobile testing with cloud devices"
→ Ask: Platform (Android), Mode (Platform), Device (Cloud)
→ Check: python3, uv
→ Create: Project with uv init
→ Configure: .env with MINITAP_API_KEY
→ Guide: Create Virtual Mobile on platform.minitap.ai
→ Generate: main.py with for_cloud_mobile config

Example 3: Full local development setup

User: "I want full control over LLM config for mobile automation"
→ Ask: Platform (Both), Mode (Local), Devices (Physical)
→ Check: All dependencies
→ Create: Project, llm-config.override.jsonc
→ Configure: Provider API keys in .env
→ Guide: Device-specific setup for iOS and Android
→ Generate: main.py with local profile config

mobile-use-setup

Mobile-Use SDK Setup Wizard

When to Apply

Setup Flow

Phase 1: Gather Requirements