prod-FARM-IOS-Core README

The project's README from github.com/Git-Agni/prod-FARM-IOS-Core. As one markdown file: README.md.

Phone Farm iOS

An open-source, standalone application for operating physical iOS devices and running scheduled TikTok workflows. It includes guided device registration, WDA/Appium supervision, live video and remote input, PostgreSQL-backed scheduling, recurring jobs, uploads, execution history, the dashboard/API server, and a built-in TikTok automation plugin.

It runs locally as-is; authentication is optional on a loopback bind. Harden it for a shared or exposed deployment by supplying your own AuthProvider (PHONE_FARM_AUTH_PLUGIN) and process supervision — no fork required. Tasks are persisted as pluginId, taskType, taskVersion, and a JSON payload, so an old schedule can never silently execute a new contract.

Live demo and setup walkthrough: gethandler.ai/ios-farm

The full engineering writeup, TikTok on 9 real iPhones reverse engineered from the screen up (Apple's test daemon, the two WebDriverAgent patches, pixel-level UI detection, OCR account switching, never posting twice): gethandler.ai/tiktok-iphone-farm

Documentation

Run the standalone application

Requirements are Node 22+, PostgreSQL, Xcode, a signed real-device WebDriverAgent, and Appium's XCUITest driver.

npm install
cp .env.example .env
npm run appium:install-driver
npm run db:up
npm run db:migrate
npm run wda:prepare

Run these long-lived processes (wrap each in a launchd agent or systemd unit for an always-on host):

npm run appium
npm run wda:service
npm run worker
npm run web

TikTok support is enabled by default. Set PHONE_FARM_PLUGINS to comma-separated ESM package names to add more task plugins. Set PHONE_FARM_AUTH_PLUGIN to an ESM authentication provider before binding WEB_HOST outside loopback; startup deliberately fails otherwise.

Plugin contract

src/plugin.ts defines the stable interfaces. A plugin can provide versioned tasks, registration checks, device-page panels, namespaced HTTP routes, and declared WDA extensions. Task execution receives the exact device, that plugin's own per-device data, resolved assets, a temporary workspace, cancellation, durable logging, safe device primitives, and an observed subprocess runner.

See PLUGIN_DEVELOPMENT.md for compatibility and trust rules.

src/example-plugin.ts is a minimal open-app plugin. Production plugins should be separate packages and should never require changes to core routing or scheduler code.

Repository policy

This repository uses GitHub-hosted CI only. Never connect production devices, Apple signing material, production databases, self-hosted runners, or deployment credentials to workflows triggered by pull requests. See SECURITY.md.

npm run check

prod-FARM-IOS-Core (Git-Agni/prod-FARM-IOS-Core)

Searching Database…

1.7K ·GitHub
Prod-FARM-IOS-Core
What is this?An open-source, self-hosted application that operates a farm of real physical iPhones from a Mac, with guided device registration, live video/remote control, PostgreSQL-backed scheduling, and a built-in TikTok automation plugin.
Is this a framework I build on, or a ready-to-run app?It's a standalone application with a dashboard/API server and a plugin system, not a library you import — you run it as a set of long-lived server processes and extend it with plugins.
How do I get it running?Install Node 22+, PostgreSQL, Xcode, a signed real-device WebDriverAgent build, and Appium's XCUITest driver, then run the Appium, WDA service, and dashboard/API processes (wrapped in launchd or systemd units) and register a device per docs/getting-started.md.
Do I need actual iPhones and Apple developer tools, or can I test with simulators?You need real, signed physical devices — setup requires Xcode and a signed real-device WebDriverAgent build plus Appium's XCUITest driver; no simulator path is described.
Is it safe to expose the dashboard outside my local network?Not out of the box — authentication is optional on a loopback bind, and startup deliberately fails if you try to bind outside loopback without supplying your own AuthProvider and process supervision.
Do I run this on the iPhones themselves, or on a Mac that controls them?It runs on a Mac, which supervises and remotely controls the connected physical iPhones over WDA/Appium — the phones are the managed devices, not the host.
What makes this different from using an iOS simulator?It operates real, physical iPhones via Apple's test daemon and patched WebDriverAgent builds rather than simulators, since the TikTok workflows depend on real-device behavior.
Does it come with TikTok automation out of the box?Yes, a built-in TikTok automation plugin is enabled by default, including OCR-based account switching and logic to avoid posting the same content twice.
Can I write my own automation plugins?Yes, src/plugin.ts defines a stable interface for versioned tasks, registration checks, device-page panels, and namespaced HTTP routes; production plugins should ship as separate packages.
How does it avoid an old schedule accidentally running a mismatched task?Tasks are persisted with pluginId, taskType, taskVersion, and a JSON payload, so a stale schedule can never silently execute against an incompatible, newer task contract.
What are similar projects?Droidline, dsh-ios, dockhand, effect-mq, rankme.fast, taskview-community, goshen-email, biointelligence-agent
Which topics is it in?htmx, fastify, mobile-automation, marketing-automation, drizzle-orm, cron, scheduler, ocr, plugin-system, postgresql, docker-compose, dashboard
Creator
Git-Agni
Size
0.2 MB
Stars
1.7K
Updated
CommitSep 07
Age
1mo
Commits · 90 Days