# Set up with your agent

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

Source: https://runfoundry.app/docs/get-started/ai-agent/

## 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](https://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](https://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](https://runfoundry.app/docs/get-started/ai-agent/#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:

```text
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.
```

> **Tested from an empty folder.** On October 26, 2026 new Codex and Claude Code chats in empty folders, on Mac accounts that had never had Foundry, were given only this brief. Each installed Foundry, activated the key, stopped at the first phone tap, then (with the phone part done) added the account and scheduled the first day's posts. Every place one stalled was fixed and the run repeated until it ran clean.

## 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](https://runfoundry.app/account), 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.

   ```bash
   xcodebuild -version
   /usr/bin/python3 --version
   ```

   What you should see:

   ```text
   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.

   ```bash
   curl -fsSL https://runfoundry.app/install.sh | sh -s -- <key>
   ```

   What you should see:

   ```text
   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.

   ```bash
   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](https://runfoundry.app/docs/reference/cli/#doctor).

   ```bash
   foundry doctor
   ```

   What you should see:

   ```text
   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
   ```

> **If the install line stops.** It prints one line that says why. If it stops before install, nothing changed; if only the key did not activate, Foundry is installed and `foundry license activate <key>` finishes it. Every message and its fix is under [Install messages](https://runfoundry.app/docs/operations/troubleshooting/#install).

## 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:

```bash
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](https://runfoundry.app/onboard.md). It is written for a chat nobody has briefed, so this one line is enough:

Paste into your agent:

```bash
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.

   ```bash
   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:

   ```text
   {
    "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](https://runfoundry.app/docs/setup/connect-iphones/#new-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](https://runfoundry.app/docs/operations/videos/)). It prints each post and its time, and the slot shows on your [dashboard](https://runfoundry.app/account) under **Queue** from the day before it posts. Phones `foundry doctor` lists as `(unenrolled)` that are not yours are skipped.

> **What the agent never does.** It never changes a phone setting itself, never posts by hand (the scheduled agents post each planned slot), and never asks you for a password or a 2FA code. The only taps are on the phone, listed under [Who does what](https://runfoundry.app/docs/get-started/ai-agent/#who-does-what).

## 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](https://runfoundry.app/docs/setup/phone-settings/).

1. **Let a new Terminal window find the command**

   ```bash
   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.

   ```bash
   foundry enroll --name phone1
   ```

3. **Install the runner and turn the phone on**

   ```bash
   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**

   ```bash
   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.

   ```bash
   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 **Trust** | Detects the phone and waits until it is ready |
| Turn the passcode off, turn on Developer Mode and restart | Checks the phone's settings and tells you what to change |
| Sign in to Xcode with your Apple ID | Builds and installs the Foundry runner on the phone |
| Trust the developer certificate on the phone, then turn on **Settings › Developer › Enable UI Automation** | Confirms 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 day | Plans the day with `foundry plan`; the Mac posts each slot on time and the receipt shows on your dashboard |
