Build an iOS app without a Mac, with Codex on a rented Mac
You can make a real iPhone app without owning a Mac. Rent a Mac, and let Codex do the Mac work for you. Codex is OpenAI's coding agent. It reads a file called AGENTS.md before it starts. We wrote one that tells Codex exactly how a Mac builds iOS apps. We tested its first three steps on one of our Macs on November 14, 2026. This page explains each step and gives you the whole file.
Why you still need a Mac
Codex can write Swift on any computer. But only a Mac can build an iOS app. Xcode, the simulator and Apple's signing tools run on macOS only. Without them, Codex writes code it can never run or see. With them, it can build the app, open it in the simulator, take a screenshot and check its own work. Our page on why an iOS coding agent needs a Mac goes deeper.
What you need
- A Mac you can reach from your computer. A MacRun Mac is a dedicated M6 Mac mini in our own private facility in New Jersey. It comes with Xcode 27.1 and Homebrew. On the agent plan, Codex is installed too.
- A ChatGPT account. Codex signs in with it. Your plan's usage limits apply.
- An Apple Developer account, later. You need it only to put the app on your own iPhone or in the App Store. It costs 99 USD a year. The simulator steps need no account.
- No Xcode experience. The file tells Codex to explain each step in plain words and show you a screenshot.
What AGENTS.md does
AGENTS.md is a plain text file of instructions. Codex reads it before every task. A file at ~/.codex/AGENTS.md applies to all your projects. A file inside a project folder applies to that project.
Our file tells Codex four things:
- What is installed on the Mac, and how to check it.
- The rules. Keep each app in its own git repo. Never put keys or passwords in git. Never ask for your Apple ID password. Check the work before saying it works.
- The exact commands to create, build, run and test an app.
- How to upload a test build to TestFlight with your API key.
Step 0: put the file in place
Open Terminal on the Mac, or connect over SSH. Download the file into Codex's folder, then start Codex. If Codex is not installed, install it with Homebrew first.
mkdir -p ~/.codex curl -fsSL https://macrun.dev/blueprint/AGENTS.md -o ~/.codex/AGENTS.md brew install --cask codex # only if codex is missing codex
The first time, choose Sign in with ChatGPT. The sign-in opens a browser on the Mac. You can finish it from the Mac's desktop in your browser.
Step 1: describe the app, and let Codex create it
An Xcode project file is hard to write by hand, for people and for agents. So the file tells Codex to use XcodeGen. Codex writes a short project.yml, and XcodeGen turns it into a real Xcode project. Codex installs XcodeGen with Homebrew when it needs it.
Then tell Codex what you want, in your own words. For example:
Make a new iPhone app called Tally. It has one big button that counts taps and remembers the count. Use SwiftUI. Follow AGENTS.md and show me a screenshot when it runs.
Codex will ask for your own reverse domain, like com.yourname. That becomes the start of the app's bundle ID.
Step 2: build, run and take a screenshot
This is the loop that makes an agent useful on iOS. Codex builds the app, starts the simulator, installs the app and takes a screenshot. Then it looks at the picture. If the layout is broken, it sees that and fixes it before you do.
SIM="iPhone 17" xcodebuild -scheme Tally -destination "platform=iOS Simulator,name=$SIM" \ -derivedDataPath build build xcrun simctl bootstatus "$SIM" -b xcrun simctl install "$SIM" build/Build/Products/Debug-iphonesimulator/Tally.app xcrun simctl launch "$SIM" com.yourname.tally sleep 3; xcrun simctl io "$SIM" screenshot /tmp/shot.png
You do not type these. Codex runs them for you. They are here so you know what it is doing.
Step 3: run the tests
The project has a test target from the start. Ask Codex to add a test for each feature. It runs them all with one command:
xcodebuild test -scheme Tally \ -destination "platform=iOS Simulator,name=iPhone 17" -derivedDataPath build
What happened when we tested it
On November 14, 2026, we ran steps 1 to 3 on one of our M6 Macs. We used XcodeGen 2.46, Xcode 27.1 and the iPhone 17 simulator. The project generated, the app built and ran, the screenshot came back, and the tests passed. We then wrote the steps down as they worked. That became this file.
Step 4: put it on your iPhone with TestFlight
A remote Mac cannot see an iPhone near you. You cannot plug your phone into it. TestFlight is the way to get the app onto your phone. You need the Apple Developer Program for this step.
- Create the app in App Store Connect, with the same bundle ID.
- Create an App Store Connect API key with the App Manager role. Download the .p8 file once and put it on the Mac in ~/.appstoreconnect/private_keys/.
- Give Codex the key ID, the issuer ID and your Team ID.
- Ask Codex to upload a test build. It archives the app and uploads it with xcodebuild and your key.
- Install the build from the TestFlight app on your iPhone.
Codex never needs your Apple ID password. The key does the signing and the upload. To be clear, we have not run this step end to end on our fleet yet, because it needs a developer account. It follows Apple's documented xcodebuild flow for API key uploads. Our publishing guide covers App Store Connect in more detail.
Step 5: automate it, if you want
- Upload on every push. A GitHub Actions runner can run on the same Mac. See our self-hosted runner guide.
- Run a task on a schedule. A LaunchAgent can start
codex execwith a task at a set time and log the result. The file tells Codex to show you how to turn it off.
The full AGENTS.md
Copy it from here, or download AGENTS.md. It is written for a MacRun Mac. On another Mac, change the first lines to match what is installed there.
# This Mac: how to build iOS apps here
You are a coding agent on a dedicated MacRun Mac mini (M6, macOS 27). The person you work with
may be new to iOS. Explain what you do in plain words, one step at a time, and show them the
result (a simulator screenshot) after each change they can see.
## What is installed
- Xcode 27.1 with iOS 27.1, 27.0 and 26.5 simulators. Check with `xcrun simctl list devices available`.
- Homebrew (`/opt/homebrew/bin`), git, Node, Ruby, fastlane, Codex and Claude Code.
- Not installed until needed: XcodeGen. Install it with `brew install xcodegen`.
## Rules
- Keep projects in `~/Projects/<AppName>`. Make each one a git repo and commit after each working step.
- Never put secrets in git: no `.p8` keys, passwords or API tokens. Keep App Store Connect keys in
`~/.appstoreconnect/private_keys/` and add `*.p8` to `.gitignore`.
- Never ask the person for their Apple ID password. Signing and uploads use an App Store Connect API key.
- The Mac does not sleep. Do not change power, sharing or network settings.
- Check the work yourself: build, run tests, and look at a screenshot before you say it works.
## 1. Create a new app
Xcode projects are hard to write by hand, so describe the project in `project.yml` and let XcodeGen
make the `.xcodeproj`:
```yaml
name: Hello
options:
bundleIdPrefix: com.example # ask the person for their own reverse domain
deploymentTarget: { iOS: "26.0" }
targets:
Hello:
type: application
platform: iOS
sources: [Sources]
settings:
base:
PRODUCT_BUNDLE_IDENTIFIER: com.example.hello
MARKETING_VERSION: "1.0"
CURRENT_PROJECT_VERSION: "1"
GENERATE_INFOPLIST_FILE: YES
INFOPLIST_KEY_UILaunchScreen_Generation: YES
INFOPLIST_KEY_UISupportedInterfaceOrientations: UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight
TARGETED_DEVICE_FAMILY: "1" # iPhone only; use "1,2" for iPad too
HelloTests:
type: bundle.unit-test
platform: iOS
sources: [Tests]
dependencies: [{ target: Hello }]
settings:
base:
GENERATE_INFOPLIST_FILE: YES
schemes:
Hello:
build: { targets: { Hello: all } }
test: { targets: [HelloTests] }
```
Write SwiftUI code in `Sources/` (an `App` struct and a `ContentView`), tests in `Tests/`, then run
`xcodegen generate`. Run it again whenever you add or remove files.
## 2. Build and run in the simulator
```sh
SIM="iPhone 17"
xcodebuild -scheme Hello -destination "platform=iOS Simulator,name=$SIM" \
-derivedDataPath build build
xcrun simctl bootstatus "$SIM" -b # boots it and waits until ready
xcrun simctl install "$SIM" build/Build/Products/Debug-iphonesimulator/Hello.app
xcrun simctl launch "$SIM" com.example.hello
sleep 3; xcrun simctl io "$SIM" screenshot /tmp/shot.png
```
Open `/tmp/shot.png` to check the screen, and show it to the person. They can also open the
Mac's desktop in Screen Sharing or the browser to look for themselves.
## 3. Run the tests
```sh
xcodebuild test -scheme Hello -destination "platform=iOS Simulator,name=iPhone 17" -derivedDataPath build
```
## 4. Test builds and uploads to TestFlight
This needs the person's paid Apple Developer account. Do these steps with them:
1. They create the app in App Store Connect (Apps, +, New App) with the same bundle ID.
2. They create an API key in App Store Connect (Users and Access, Integrations, App Store Connect API,
role App Manager). They download the `.p8` file once and put it in `~/.appstoreconnect/private_keys/`.
You need three values: the key ID, the issuer ID, and their Team ID (Membership page).
3. Set the Team ID in `project.yml` (`DEVELOPMENT_TEAM`, with `CODE_SIGN_STYLE: Automatic`) and regenerate.
Then each upload is:
```sh
KEY_ID=...; ISSUER=...; KEY=~/.appstoreconnect/private_keys/AuthKey_$KEY_ID.p8
AUTH="-allowProvisioningUpdates -authenticationKeyPath $KEY -authenticationKeyID $KEY_ID -authenticationKeyIssuerID $ISSUER"
xcodebuild -scheme Hello -configuration Release -destination "generic/platform=iOS" \
-archivePath build/Hello.xcarchive archive $AUTH
xcodebuild -exportArchive -archivePath build/Hello.xcarchive \
-exportOptionsPlist ExportOptions.plist -exportPath build/export $AUTH
```
`ExportOptions.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>method</key><string>app-store-connect</string>
<key>destination</key><string>upload</string>
<key>teamID</key><string>TEAM_ID_HERE</string>
</dict></plist>
```
Raise `CURRENT_PROJECT_VERSION` before every upload; App Store Connect rejects a repeated build number.
The build shows in TestFlight after Apple processes it, which can take a while. If the person
prefers fastlane, `fastlane pilot` does the same with the same API key.
## 5. Automate it
- To upload on every push, a GitHub Actions self-hosted runner can run on this Mac. Ask first.
- To run a task on a schedule, use a LaunchAgent in `~/Library/LaunchAgents` that calls
`codex exec "<task>"`, and log to a file. Show the person how to turn it off.
## Limits
- No physical iPhone can be plugged in. Use the simulator here and TestFlight on their own phone.
- Apple's review is done by Apple. You can prepare the build, but the person submits for review.
Tips for working with Codex on an app
- Ask for one small change at a time. Look at the screenshot after each one.
- Let Codex commit after every working step. Then a bad change is easy to undo.
- Push the repo to GitHub, so your code also lives off the Mac.
- Never paste keys or passwords into the chat. Put the .p8 file on the Mac yourself.
- When something looks wrong, say what you see. Codex can take another screenshot.
What this will not do
- It cannot test on a phone plugged into the Mac. Use the simulator and TestFlight.
- Apple reviews every App Store app. You submit the app for review yourself.
- Codex can make mistakes. You decide what ships.
- We provide the Mac and the file. We do not build your app.
What it costs
A MacRun agent Mac is $169 a month, with Xcode 27.1 and Codex installed. It never sleeps, so Codex can keep working while your own computer is off. Your ChatGPT plan pays for Codex. The Apple Developer Program is 99 USD a year, and only needed for TestFlight and the App Store.
Who should not rent a Mac for this
If you already own a Mac, use it. The same file works there. If you want an app with no code at all, a no-code builder may suit you better. For other routes, read developing iOS apps without a Mac.
Frequently asked questions
Can I build an iOS app without a Mac by using an AI agent?
+
The agent can write the code anywhere, but building and running an iOS app needs Xcode, which runs only on macOS. Rent a Mac, run Codex on it, and the agent can build, run the simulator and check its own work.
What is AGENTS.md?
+
A plain text file of instructions that Codex reads before every task. A file at ~/.codex/AGENTS.md applies to all projects. A file in a project folder applies to that project. Ours tells Codex how to create, build, test and upload an iOS app on a Mac.
Did you test this AGENTS.md?
+
We tested steps 1 to 3 on one of our M6 Macs on November 14, 2026. We used XcodeGen 2.46, Xcode 27.1 and the iPhone 17 simulator. The TestFlight step has not been run end to end yet. It follows Apple's documented xcodebuild flow for uploads with an App Store Connect API key.
Do I need an Apple Developer account?
+
Not to build and run the app in the simulator. You need the Apple Developer Program, 99 USD a year, for TestFlight on your iPhone. You also need it to publish on the App Store.
Can I test the app on my own iPhone?
+
Yes, through TestFlight. Codex archives and uploads a test build, and you install it from the TestFlight app. You cannot plug your iPhone into a remote Mac.
Does Codex need my Apple ID password?
+
No. The file tells Codex never to ask for it. Signing and uploads use an App Store Connect API key, which you create and place on the Mac yourself.