Working from Windows

Everything in Ploa works from a Windows PC except building the iPhone app itself, which needs a Mac with Xcode. Your agent, the store details, Android builds, screenshots from the Android emulator, the web and the app's server all work from Windows. The iPhone build runs on a Mac somewhere else, and Ploa takes it from there to TestFlight and the App Store.

Install

In PowerShell:

irm https://ploa.dev/install.ps1 | iex
ploa login
ploa mcp install

The script checks for Node 24, puts the files in %USERPROFILE%\.ploa\cli and a small ploa.cmd launcher in %USERPROFILE%\.ploa\bin, which it adds to your own PATH (not the machine's). Nothing runs as administrator. Open a new terminal afterwards, and restart your agent, so they see the new PATH. Update later with ploa update.

Or with npm: npm install -g @ploa/cli. Either way, ploa mcp install writes what your agents need to start Ploa on Windows (for an npm install, cmd /c npx.cmd, since agents start a server without a shell).

What works on Windows

Not on Windows: building the iPhone app on this computer, and screenshots from the iOS Simulator. ploa doctor says what this computer has and where iPhone builds go instead.

The iPhone app from Windows

Your agent asks you where it builds, and says before a build that costs you minutes:

• On GitHub's Macs. An owner allows them in the app's GitHub settings, and the build runs on GitHub from what's pushed. On a private repository a Mac minute counts as ten of your GitHub minutes (an iPhone build is about 150 to 200); on a public one it's free.
• On a Mac of yours or a teammate's, as a GitHub runner: ploa runner on that Mac. See GitHub.
• In Xcode Cloud. Apple builds and signs it, and Ploa follows it to TestFlight. Its first step is done once in Xcode on a Mac. See Setting up Xcode Cloud.

iPhone screenshots: the iOS Simulator needs a Mac, so take them on that Mac, or make them at the sizes ploa_screenshot_specs gives and upload them with ploa_screenshot_upload (ploa_screenshot_check checks each first).

A repository committed from Windows

Windows keeps no "executable" mark on files and may save scripts with Windows line endings (CRLF), so gradlew committed from Windows doesn't start on a Mac, on Linux or on GitHub ("Permission denied", or "bad interpreter"). Ploa fixes the wrapper before Gradle runs there and says so in the build's log. To fix it in the repository once:

git update-index --chmod=+x android/gradlew

and add a .gitattributes file at the repository's top, so scripts keep LF endings:

gradlew text eol=lf
*.sh text eol=lf

The same goes for ios/ci_scripts/ci_post_clone.sh when you use Xcode Cloud: ploa xcode-cloud says so when it adds it.

WSL

Run Ploa either in Windows or inside WSL, not half in each: your agent, ploa and the Android SDK should be on the same side. Inside WSL it's Linux: install with curl -fsSL https://ploa.dev/install.sh | sh, and use the Android SDK for Linux.

When something doesn't work

More: Troubleshooting.