Operations
When something breaks
What to check first, the commands that show what happened, and how to reach a person.
Check these first
Dashboard says No Mac activated yet
Open Terminal on the Mac and run foundry status. If it says the license is not active, run foundry license activate with your key.
A phone shows Offline
Unlock it, check its cable to the Mac, and run foundry doctor. It names what blocks that phone. Then check it against Phone settings.
A post shows Unknown
The share was pressed but not confirmed. Check the account in the app. Foundry never sends it again, so nothing double posts.
Needs you: login, 2FA or checkpoint
Only you can clear these. Open the app on that phone, finish the step, and the next slot posts.
Phone says Unable to Verify App, or the runner will not open
iOS has not checked the Foundry runner with Apple yet, and it needs internet once to do it. Connect the phone to Wi-Fi (or a SIM with working data) and run /usr/bin/python3 ~/.local/bin/foundry_onboard.py scan again; the check happens by itself. Still stuck? Settings › General › VPN & Device Management › Apple Development › Verify App.
Timed out while enabling automation mode
The runner is trusted but iOS will not hand it control. Turn the passcode off (Settings › Face ID & Passcode › Turn Passcode Off), then turn on Settings › Developer › Enable UI Automation, and run foundry_onboard.py scan again.
TikTok posts show Unknown often
TikTok's check is the least reliable in this alpha. The post usually went out; look at the profile.
Install messages
The install line stops at the first problem, prints one line starting foundry:. Fix what it names and run the same line again; it picks up where it stopped. Only the last message comes after Foundry is installed, and foundry license activate <key> finishes that one.
| What it says | What to do |
|---|---|
pass your license key | The key is missing or cut off. Copy it again from your welcome page or Setup on your dashboard; it starts with fdy1. and goes after sh -s --. |
Xcode is not installed | Install Xcode from the App Store, open it once and accept its license. |
Xcode 15 or newer is needed (xcrun devicectl is missing) | Update Xcode from the App Store, open it once, then run the line again. |
/usr/bin/python3 3.9 or newer is needed | Run xcode-select --install and accept the prompt. |
could not reach https://runfoundry.app | The Mac is offline or a network filter blocks it. Check the connection. |
that license key was not accepted | The key was mistyped. Copy it again with Copy key, never by hand. |
your plan is not active | The trial ended or a payment failed. Open Billing on your dashboard. |
the download is not out yet, so nothing was installed | Your release isn't published yet. Nothing is charged before a full week with the download; run the same line the day your dashboard shows it. |
Foundry is installed, but the key did not activate | Usually every Mac seat on the plan is taken. Free one with Free this seat under Billing › Mac seats on your dashboard, then run foundry license activate <key>. |
command not found: foundry | This Terminal window doesn't know ~/.local/bin yet. Run export PATH="$HOME/.local/bin:$PATH", or open a new window after the PATH step. |
What happened, from Terminal
foundry doctor # what blocks each phone
foundry status # phones, today's plan, warm-ups, last events
foundry watch # live results as posts run
foundry incidents # every failed or unknown post, with screenshots and the log
foundry incidents --resolve ID # after the cause is fixedHand any incident to your agent as is: it holds the receipt, the log tail and the screenshots, about 2 KB.
Signing, the Apple hold and your Mac
Dashboard warns the signing certificate ends soon
The runner on each phone is signed with your Apple Developer team, and it stops opening the day that signing ends. A free Apple account lasts 7 days, so the warning comes 2 days ahead; a paid team lasts a year, so it comes 30 days ahead. Run foundry lane up <phone> --team <team id> for each phone before the date. Open Xcode once first if it asks you to sign in.
A new phone says Apple hold
Apple can take 24 to 72 hours to accept a phone added to your team, and the runner can't install until it does. Leave the phone plugged in and run foundry lane up <phone> --team <team id> again the next day. The hold clears from the dashboard on its own once the runner installs.
Phone checks on the dashboard
Each phone shows paired, Developer Mode, UI Automation, the disk image, iOS version, runner installed and runner answering. They are read about once an hour. A blank check means it couldn't be read, not that it failed.
Failure reports
Off by default. Turn them on under Setup › Your Mac on your dashboard. Each failed post or warm-up then saves a small screenshot of the phone and the last 300 log lines, scrubbed of keys and passwords. Open one from the Report link in Issues. Reports are kept 30 days. Turning them off deletes what was waiting on the Mac.
Keep the Mac awake
On by default, so posts and warm-ups run on time. Turn it off under Setup › Your Mac, or run foundry keep-awake off (and on to undo). A sleeping Mac posts nothing until it wakes.
A newer Foundry is out
The dashboard shows it next to your version. Run foundry update check to see it from Terminal, then run your install line again to update. Your phones, accounts and plans stay.
Where your files are
| What | Where |
|---|---|
| Everything Foundry keeps | ~/Library/Application Support/Foundry |
| Today's plan | fleet/drip-plan-<date>.json |
| Receipts | fleet/<phone>/state/post-receipts/ |
| Logs | agent-cli/logs/ |
Reach a person
Use the support form. It goes straight to the team's inbox and a person answers by email, usually the same day. Name the phone and account, and never send a password or a code.
If it needs hands on the Mac, turn on support access and we fix it there.