Get started

Paste one brief into Claude Code, Codex or Cursor and it sets Foundry up, stopping only for the taps a person has to make.

The brief

After checkout, your welcome page and your dashboard (under Setup) have a brief with your license key already in it. Paste it into your agent on the Mac your iPhones plug into.

Have two things ready: a paid Apple Developer Program team (each phone's runner is signed under it; a free Apple ID will not do) and its 10 character team id, from developer.apple.com/account under Membership details. Keep the Mac awake and logged in, with the phones plugged in, whenever posts are due.

For the agent: every step is also in plain text at runfoundry.app/onboard.md. Read our pages with curl -fsSL; the host refuses Python's default urllib user agent (403). Every docs page reads as Markdown at its address plus .md (this one: /docs/get-started/ai-agent.md).

The agent installs Foundry, activates your key and walks each phone to ready. The only things left to you are signing in to Xcode once and the taps on the phone itself, listed under Who does what, and the agent tells you exactly which one is next. The brief reads like this, with your key in it:

The brief
Set up Foundry on this Mac. Run this in Terminal: `curl -fsSL https://runfoundry.app/install.sh | sh -s -- <key>`. It downloads Foundry, installs it and activates my license key. Then follow https://runfoundry.app/docs/get-started/ai-agent step by step: get every iPhone to ready. Only for a tap that needs a hand on the phone, tell me exactly what to tap.

Install

Do this on the Mac your iPhones plug into, in Terminal. You need your license key: it is on your welcome page and under Setup on your dashboard, and it starts with fdy1.. Every "What you should see" below is copied from a real run on a Mac that had never seen Foundry.

  1. Check Xcode and Python

    Foundry signs a small runner app onto each iPhone, so it needs Xcode 15 or newer, opened once with its license accepted. Python 3.9 or newer at /usr/bin/python3 comes with Xcode. If either line errors, install Xcode from the App Store, open it once, then run them again.

    Terminal
    xcodebuild -version
    /usr/bin/python3 --version
    What you should see
    Xcode 26.6
    Build version 17F113
    Python 3.9.6
  2. Run the install line with your key

    It asks runfoundry.app for the release on your license, unpacks it in your home folder, installs the foundry command and turns your key on for this Mac. It never touches a phone. Run it again later to update; your phones, accounts and receipts are kept.

    Terminal
    curl -fsSL https://runfoundry.app/install.sh | sh -s -- <key>
    What you should see
    foundry: asking https://runfoundry.app for the release on your license
    foundry: downloading 0.7.0-alpha.13
    foundry 0.7.0-alpha.13 installer
      …
    installed. next:
      …
    foundry: activating your license on this Mac
    Solo: 0 of 1 iPhone enrolled, trialing, valid until 2026-11-09 (you@example.com)
  3. Let Terminal find the command

    The command lives in ~/.local/bin. The first line works in this window; the second keeps it for every new window.

    Terminal
    export PATH="$HOME/.local/bin:$PATH"
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
  4. Check the Mac

    foundry doctor lists what still blocks this Mac and each phone, and the command that fixes it. On a Mac with no phone set up yet, two lines are expected: FAIL provisioning profiles 0 (the first foundry lane up makes the profile, after you sign in to Xcode under Xcode › Settings › Accounts) and phones this Mac has met before listed as state=unavailable until they are on the cable. Every line is explained in the CLI reference.

    Terminal
    foundry doctor
    What you should see
    foundry 0.7.0-alpha.13 doctor
      ok  xcode            /Applications/Xcode.app/Contents/Developer
      ok  devicectl        518.33
      ok  python           3.13.13
      ok  FOUNDRY_HOME     ~/Library/Application Support/Foundry
      ok  fleet manifest   0 lanes
      ok  accounts.json    0 enabled
      ok  ocr binary       ~/foundry-0.7.0-alpha.13/foundry/build/foundry-vision-ocr
      FAIL provisioning profiles  0 (needed to sign the runner; …)
      --  agent com.foundry.post-runner  not installed
      --  agent com.foundry.warm-runner  not installed
      --  agent com.foundry.warm-plan    not installed
      NOT ready -- fix the FAIL/<- lines above

Install by hand

Same result without the install line. Press Download Foundry under Setup on your dashboard, then run these with the version from the file name in place of <version> (for example 0.7.0-alpha.13), so an older download is never picked by mistake.

Terminal
tar -xzf "$HOME/Downloads/foundry-<version>.tar.gz" -C "$HOME"
"$HOME/foundry-<version>/foundry/install.sh"
"$HOME/.local/bin/foundry" license activate <key>
"$HOME/.local/bin/foundry" doctor

Connect the phones

Plug every iPhone into the Mac, then hand your agent the setup brief at runfoundry.app/onboard.md. It is written for a chat nobody has briefed, so this one line is enough:

Paste into your agent
Set up my iPhones for Foundry. Follow https://runfoundry.app/onboard.md

The agent fetches the first-run tool and runs it. The tool reads the license key you activated, finds every iPhone on the cable and reads each one's state from the phone itself:

One step, one phone

  1. The agent runs the first-run tool

    --json is the mode written for agents: each phone comes back with its step, the one thing to do (next.say) and where to tap (next.path). A phone this Mac has met before but that is not on the cable right now comes back at plug. On a Mac that lists other people's phones, add --phone <UDID> (or the iPhone's own name from Settings, General, About; many phones are just "iPhone", and a name that matches more than one phone stops the run with each UDID; the short name comes later, at foundry enroll), or put their UDIDs one a line in ~/.foundry-agent/never-touch first: the tool and foundry doctor then leave them alone. With no iPhone on the cable, phones is empty and the top level next says to plug one in.

    Terminal
    mkdir -p ~/.local/bin
    curl -fsSL https://runfoundry.app/foundry_onboard.py -o ~/.local/bin/foundry_onboard.py
    /usr/bin/python3 ~/.local/bin/foundry_onboard.py --json
    What you should see
    {
     "phones": [
      {
       "product_type": "iPhone13,1",
       "name": "iPhone 12 mini",
       "ios": "26.3",
       "step": "plug",
       "mapped": false,
       "next": {
        "say": "Plug the iPhone into this Mac with a data cable, unlock it and tap Trust.",
        "path": "Data cable (not a charge only cable). On the phone: Trust This Computer, Trust."
       }
      }
     ],
     "summary": { "phones": 1, "ready": 0, "mapped": 0 }
    }
  2. It tells you one step for one phone

    In the phone's own words, for example "Turn the passcode off." with where it is: Settings › Face ID (or Touch ID) & Passcode › Turn Passcode Off. It never pastes the whole list at you.

  3. You tap it and say done

    The agent runs the tool again. The phone's state decides what comes next, not what anyone remembers, so a step that didn't stick comes back.

  4. A phone model Foundry hasn't seen yet is mapped on the spot

    Once that phone reads ready, the tool opens the Settings screens Foundry needs, records where each row sits, changes nothing, and uploads the map. It takes about 15 minutes; leave the phone plugged in. Every Foundry rack with that model starts from the map after that. See New phone models.

  5. Every phone reads ready

    The agent finishes on the Mac: foundry enroll --udid <udid> --name <phone> and foundry lane up <phone> --team <team id> (the runner step; <phone> is the short name it enrolled under), foundry lane enable <phone> once it answers ready, foundry accounts add --id instagram-<handle> --platform instagram --phone <phone> --handle <handle> --posts 2 --warms 2,3 for each handle you give it (an account goes on an enrolled phone, so this waits for the phone), foundry warm-plan --days 7, foundry install-agents, then foundry plan --date YYYY-MM-DD --videos videos.json --write for your first day of clips (Your videos). It prints each post and its time, and the slot shows on your dashboard under Queue from the day before it posts. Phones foundry doctor lists as (unenrolled) that are not yours are skipped.

The first phone, by hand

If you'd rather run the commands yourself, this is the same setup without the first-run tool. foundry doctor lists what is still missing on this Mac and what to run next. The full guide ships inside the download as README.md. Set the phone up first: Phone settings.

  1. Let a new Terminal window find the command

    Terminal
    export PATH="$HOME/.local/bin:$PATH"
  2. Enroll the phone

    Pick a short name for it, like phone1: every later command calls the phone by that name (<phone> below). If this Mac has met more than one phone, foundry enroll lists them; pick yours with --udid and its id.

    Terminal
    foundry enroll --name phone1
  3. Install the runner and turn the phone on

    Terminal
    foundry lane up <phone> --team <your Apple Developer team id>
    foundry lane enable <phone>
  4. Add an account that is signed in on that phone

    Terminal
    foundry accounts add --id instagram-myhandle --platform instagram --phone <phone> --handle myhandle --posts 2 --warms 2,3
  5. Start warm-ups and the scheduled agents

    install-agents loads three launchd jobs. The post-runner wakes every minute and posts only a slot planned for that minute; with no plan written it does nothing.

    Terminal
    foundry warm-plan --days 7
    foundry install-agents

Who does what

You (a few taps, once)Your agent
Plug in the iPhone, unlock it, tap TrustDetects the phone and waits until it is ready
Turn the passcode off, turn on Developer Mode and restartChecks the phone's settings and tells you what to change
Sign in to Xcode with your Apple IDBuilds and installs the Foundry runner on the phone
Trust the developer certificate on the phone, then turn on Settings › Developer › Enable UI AutomationConfirms the runner is installed and healthy
Log in to TikTok, Instagram or YouTube — or X, Reddit, Snapchat or LinkedIn in Beta (Facebook rides Instagram in Beta)Links each account to its phone under the handle you give it
Tell it which clips post on which dayPlans the day with foundry plan; the Mac posts each slot on time and the receipt shows on your dashboard
Copied