# FAQ
Frequently asked questions about installing, licensing and scripting with AutoTouch.
# Installation & requirements
# Does AutoTouch need a jailbreak?
Yes. AutoTouch simulates touches and key presses at a level that requires a jailbroken device. It cannot run on a stock iOS device or from the App Store. Packages are built for rootful, rootless and roothide environments. Use the package that matches your jailbreak; individual features can also depend on the iOS version.
# How do I install AutoTouch?
Add the official repository (opens new window) in your device’s package manager, then install AutoTouch. See How to install.
# Licensing
# How long is a license valid?
Check the plan and expiry shown in license management. Time-limited licenses start their validity period on first activation; transferring an activated license does not restart that period. Renew an expired license from the License view.
# How many devices can one license activate?
A transferable license activates one device at a time. Activating another device deactivates the previous one. A 24-hour activation lock can apply when activating by key; the authenticated license owner can be exempt. Sign in to the owning account and follow the status shown by license management.
# I paid but the device wasn't activated — what now?
Open License in settings and retrieve the purchase using the available lookup method. Email-based lookup requires signing in. Activate the current device with the purchased license and check the downloaded license status before purchasing again.
# I bought a license on another device. Can I use it here?
Yes. Use Activate Current Device in the License view and enter the license key. Sign in to the owning account if an activation lock is shown.
# Running scripts
# How do I stop a script that won't stop?
Hold Volume Down (or your Activator gesture). A long press force-stops playback. From a script you can also call stop().
# My script uses coordinates that don't match on another device. Why?
AutoTouch uses native pixel resolution as its coordinate system, and different devices have different resolutions. Hard-coded coordinates from one device rarely match another. Prefer resolution-independent techniques — findColors, findImage or ocr — or compute coordinates from getScreenResolution(). See Coordinate, Size and Orientation System.
# Should I write scripts in Lua or JavaScript?
Use Lua. Current builds support Lua only. Recordings produce .lua, packages use main.lua, and .js files cannot run as scripts. JavaScript and JSBridge pages are historical references for older versions.
# How do I pick coordinates and colors for findColors / findImage?
Take a screenshot with Snap or the iOS screenshot gesture. Use the in-app Function Helper to read coordinates and colors. For image matching, copy/import the target image from Photos into your script folder and use that file path.
# What changed in findImage?
Use findImage(options) for local searches with rotation/scale support, an optional source image, and detailed results. For example, findImage({image = "images/button.PNG", count = 1}) returns matches whose centers are read as matches[1].center.x and .y. The old positional call still returns {{x, y}, ...}; update result handling when migrating. No match returns {}; errors can be caught with pcall.
# Screen lock
# How do I lock or unlock the screen from a script?
Call the built-in lockScreen() and unlockScreen(). unlockScreen() natively wakes the device, authenticates and dismisses the lock screen to the home screen. If the device has a passcode, pass it: unlockScreen("1234"). Check its boolean return: true means the native home-screen check succeeded; false requires checking the device and is not proof that it remains locked. Do not loop passcode attempts. nativeUnlockScreen() only requests system unlock and returns no success status. See unlockScreen.
A passcode passed to
unlockScreen("1234")is stored in plain text in your script — treat any script that embeds it as a secret, and distribute it as a password-protected.atepackage.
# Encryption & distribution
# What's the difference between a password and a no-password encrypted package?
A password-protected package is strongly encrypted (AES-256) and only opens with the correct password — ideal for paid scripts. A no-password package is lightly obfuscated so it can run freely on any device and any app version; it offers no real confidentiality by design. See How to encrypt scripts.
# How do I manage scripts from my computer?
Turn on the Web Server in settings and open the shown URL in a browser, or turn on the WebDAV Server and connect with any WebDAV client. Both work over your LAN. For automation, see the HTTP APIs.
# Troubleshooting
# findImage returns no matches or raises an error.
An empty table means the search completed without a match. Check the target crop, search region, confidence and scale/angle range. A Lua error means the operation failed: check the file path, image readability and screen capture availability. Use the error-handling example to tell these cases apart.
# Why does OCR_METHOD.TESSERACT_LOCAL fail?
The constant is retained for compatibility, but that backend is unavailable in current builds. Use IOS_VISION for local OCR on supported iOS versions, or explicitly select AI_CLOUD to send the image to the remote service. There is no automatic cloud fallback. See OCR.
# Why does a relative file path work in one script but fail in another?
Image and other script-resource paths are resolved relative to the running script. Encrypted packages may run from a temporary directory. Keep assets inside the package; use currentDir() for runtime resources and rootDir() for persistent files. See Paths and packages.
# The computer cannot reach the device.
Check that both devices are on the same LAN and use the address shown in AutoTouch settings. The Web Server, WebDAV and ControlPlane are separate services. ControlPlane uses HTTP on device loopback and HTTPS for its enabled LAN listener. A missing TLS configuration prevents the ControlPlane LAN listener from starting. See HTTP connections.
# inputText does nothing.
Focus an editable text field and enable the input-text feature in AutoTouch settings. Some app fields or compatibility settings may prevent input. Check the runtime log; do not assume that a successful tap has focused the field.
# What should I include in a bug report?
Include the AutoTouch version, device model, iOS version, jailbreak type, exact error text, and the smallest script that reproduces it. For matching problems, include the target image and a screenshot of the searched area. captureDebugInfo() can supply capture diagnostics. Remove passcodes, tokens and license keys before sharing logs or scripts.