Mobile-Use SDK Setup Wizard

Interactive guide for setting up the Minitap mobile-use SDK with support for iOS and Android devices, Platform and Local modes.

When to Apply

This skill activates when users want to:

• Set up mobile automation for an app
• Configure the Minitap mobile-use SDK
• Connect physical iOS or Android devices
• Set up cloud virtual devices
• Create a new mobile testing project

Setup Flow

Phase 1: Gather Requirements

Ask the user these questions using the AskUserQuestion tool:

1. Target Platform

• Question: "Which platform(s) do you want to automate?"
• Options: iOS only, Android only, Both iOS and Android

1. 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

1. Device Type (if iOS selected)

• Question: "What iOS device setup do you need?"
• Options:
• Physical device (iPhone/iPad via USB)
• Simulator (Xcode iOS Simulator)

1. 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:

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

MINITAP_API_KEY=<their-key>

1. Add .env to .gitignore

For Local Mode:

1. Copy the config template:

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

1. Edit llm-config.override.jsonc with preferred models (refer to llm-config.defaults.jsonc for recommended settings)
2. 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:

1. Open WebDriverAgent in Xcode:

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

1. Sign these targets with their Apple ID:

• WebDriverAgentRunner
• WebDriverAgentLib
• IntegrationApp

1. Change Bundle IDs to unique values
2. Build IntegrationApp once with device connected
3. Trust developer certificate on device: Settings → General → VPN & Device Management

Android Physical Device:

Inform user they need to:

1. Enable Developer Options (tap Build Number 7 times)
2. Enable USB Debugging
3. 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

Troubleshooting

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