> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autogrowth.farm/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AutoGrowth runs social accounts on real phones. Everything a page describes happens on a physical device in the customer's own fleet, never through a social platform's API.
> The Companion is a macOS desktop app that runs on the customer's own Mac and manages the phones over USB — iPhones through WebDriverAgent, GrapheneOS phones through ADB and scrcpy. Nothing runs while the Companion is closed.
> The Companion builds, signs and installs WebDriverAgent on each iPhone itself. Never tell a customer to sign WebDriverAgent by hand in Xcode; Xcode is a prerequisite the Companion drives, not a step the customer performs.
> Autogrowth MAX is a one-time, invite-only lifetime license bought from the organization's credit balance, not a subscription tier. It is required to run any automation, workflow or Incubator program. Without a price set for that organization, the purchase is refused.
> An automation is one of AutoGrowth's built-in definitions; a script is a graph the customer builds in the Script Builder. The Script Builder is locked platform-wide, so never present building a script as something a customer can do today.
> An API key is a bare 64-character hex string with no prefix. It is shown once, at creation, is sent as `Authorization: Bearer <key>`, and can never be read back.
> An API key sees only the key owner's own accounts, content, collections, prompts, scripts and executions. Devices and tags are organization-scoped, and a non-owner sees only the devices assigned to them or carrying one of their tags. The automation catalog is global.
> There is no pagination. List endpoints return the whole set; the only limiting parameter anywhere is `limit` on `GET /v1/executions`, which defaults to 50 and has no offset to page with.
> Remote control and the live screen are dashboard-only, over WebSocket and MJPEG. Neither is part of the public API.
> The MCP server is hosted at https://mcp.autogrowth.farm and authenticates with OAuth. It is not an npm package and there is nothing to install locally. Its tools inherit exactly the scope of the API key behind them.
> Android support is partial and GrapheneOS-only: those phones appear in the fleet and can be watched and remote-controlled, but they cannot run scripts or automations.
> Never document Hi Katie or any persona feature. When a page and the code disagree, the code wins — check a claim against the source before repeating it.

# Install the Companion

> Download the Companion for macOS, install the tools it needs, and sign in with a license key that locks to that Mac.

The Companion is the macOS app that connects your phones to AutoGrowth. It has to
be installed on the Mac the phones are physically plugged into, and it has to stay
open for anything to run.

## Before you start

* A **Mac** — Apple Silicon or Intel. There are separate downloads for each.
* The Mac's **login password**. macOS asks for it once per session on iPhones
  running iOS 17 or newer.
* A few command-line tools, listed below. Installing those takes longer than
  installing the Companion itself, so start there if you are in a hurry.

## Get the app

There is no public download page. An **organization owner** creates a one-time
link from the dashboard, and that link works once.

<Steps>
  <Step title="Open Settings → Downloads">
    The section is described as "Create one-time download links for the app".
    Only owners can see it; if you are not one, ask for a link.
  </Step>

  <Step title="Pick the chip your Mac has">
    Press **Apple Silicon (M-Series)** for an M-series Mac, or the Intel button
    beside it. The dashboard cannot detect this from your browser — check the
    Apple menu → **About This Mac** if you are unsure.
  </Step>

  <Step title="Open the link">
    A **Download Link Created** card appears with the link and its expiry. Paste
    it straight into a browser address bar. It lasts 24 hours by default and can
    only be used once.
  </Step>

  <Step title="Open the DMG and drag the app to Applications">
    The app is called **AutoGrowth Companion**.
  </Step>
</Steps>

<Frame caption="Settings → Downloads, where an owner mints a one-time installer link.">
  <img src="https://mintcdn.com/autogrowth/XpowNsqf1wRaYnfV/images/dashboard-downloads.png?fit=max&auto=format&n=XpowNsqf1wRaYnfV&q=85&s=002924d7a1ead4eca41247b16365c4bb" alt="The Downloads section of dashboard Settings showing the Apple Silicon (M-Series) and Intel download buttons and a Download Link Created card containing a one-time link and its expiry time" width="1600" height="811" data-path="images/dashboard-downloads.png" />
</Frame>

If a link stops working, the message says which of the two things happened:
"Download link has already been used" or "Download link has expired". Both are
fixed the same way — ask an owner for a new one.

## Install the tools it needs

The Companion drives phones using standard Apple and Android command-line tools.
They are not bundled, so install them on the Mac yourself. Everything marked
"iPhones" is needed before an iPhone will work; the Android rows are only needed
for GrapheneOS phones.

| Tool                               | For               | Install with                                                     |
| ---------------------------------- | ----------------- | ---------------------------------------------------------------- |
| `python3`                          | iPhones           | `brew install python3`                                           |
| `pymobiledevice3` (4.0.0 or newer) | iPhones           | `python3 -m pip install --break-system-packages pymobiledevice3` |
| Xcode                              | iPhones           | Install it from the App Store                                    |
| `iproxy`                           | iPhones           | `brew install libimobiledevice`                                  |
| `idevice_id`                       | iPhones           | `brew install libimobiledevice`                                  |
| `ideviceinstaller`                 | iPhones           | `brew install ideviceinstaller`                                  |
| `adb`                              | GrapheneOS phones | `brew install --cask android-platform-tools`                     |
| `ffmpeg`                           | GrapheneOS phones | `brew install ffmpeg`                                            |

<Info>
  Xcode has to be installed, but you never open it. The Companion uses parts of it
  in the background to see iPhones and install onto them. If Xcode is installed
  and the Companion still complains about it, the screen shows the exact command
  to fix it: `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`.
</Info>

### The dependency screen

The Companion checks for these tools every time it starts — right after you sign
in — and shows what is missing with the install command and a **Copy** button
beside each one. The command it shows is generated for your Mac's own setup, so
prefer it over the table above if the two differ. Run the commands, then press
**Re-check Dependencies**.

Which screen you get depends on how much is missing:

| Screen                                 | Meaning                                                                                            |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Missing System Dependencies**        | Neither iPhones nor GrapheneOS phones can be managed. You cannot get past this screen              |
| **Some Device Support Is Unavailable** | One platform is ready and the other is not. Press **Dismiss** and carry on with the one that works |

## Sign in with a license key

The Companion does not use your email and password. It signs in with a **license
key** you create in the dashboard.

<Steps>
  <Step title="Create the key in the dashboard">
    Go to **Settings → Companion Keys** and press **Create Key**. Name it after
    the Mac it is for — the placeholder suggests "e.g., MacBook Pro, Office PC".
  </Step>

  <Step title="Copy it immediately">
    The dashboard says **"Copy this key now. You won't be able to see it
    again!"** and means it. If you lose it, delete it and make another.
  </Step>

  <Step title="Paste it into the Companion">
    Open the Companion, paste the key into the **License Key** field and press
    **Continue**. You land on the **Devices** page.
  </Step>
</Steps>

<Frame caption="The Companion's sign-in screen. One field, one key.">
  <img src="https://mintcdn.com/autogrowth/XpowNsqf1wRaYnfV/images/companion-sign-in.png?fit=max&auto=format&n=XpowNsqf1wRaYnfV&q=85&s=7bf8818ad05eac5eb71fd43e9c1dbaf0" alt="The AutoGrowth Companion login window showing the subtitle Enter your license key to continue, a single License Key input, a Continue button, and the note Your license key binds to this device on first use" width="1600" height="1000" data-path="images/companion-sign-in.png" />
</Frame>

<Warning>
  The field's placeholder reads `XXXX-XXXX-XXXX-XXXX`, but a real key is a single
  run of 64 letters and digits with no dashes. Paste exactly what the dashboard
  gave you and do not reformat it.
</Warning>

### One key, one Mac

The first Mac that signs in with a key claims it. The Companion says so under the
field: **"Your license key binds to this device on first use"**. From then on that
key works on that Mac and nowhere else, and there is no way to unbind it.

Try it on a second Mac and you get: "This license key is already bound to another
computer. Contact support to move it."

To give a different Mac access, replace the key rather than move it:

1. In the dashboard, open **Settings → Companion Keys** and delete the old key.
2. Create a new one.
3. Sign in with the new key on the new Mac.

The phones are unaffected — they belong to your organization, not to the key.

### Staying signed in

The Companion re-checks the key with the server every five minutes, and again at
every launch. If it cannot reach the server it retries a few times and then signs
you out — which is why a Mac that lost internet for a while can be sitting on the
login screen when you come back. Paste the key again and carry on.

### If sign-in is refused

| What it says                                                                         | What to do                                                             |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| "This license key isn't valid. It may have been mistyped, deleted, or revoked."      | Copy a fresh key from **Settings → Companion Keys** and paste it again |
| "This license key is already bound to another computer. Contact support to move it." | Delete that key in the dashboard and create a new one for this Mac     |
| "This license has been revoked. Contact support if you believe this is a mistake."   | Create a new key. If it keeps happening, write to support              |
| "This computer has been banned." / "This account has been disabled."                 | Nothing self-serve. Contact support                                    |
| "Couldn't reach the license server. Check your internet connection and try again."   | You are offline, or a VPN or firewall is in the way                    |
| "Your session ended. Enter your license key to continue."                            | The five-minute re-check failed. Paste the key again                   |
| "An update is required before you can sign in."                                      | Get a fresh DMG — see [Updates](#updates)                              |

## What happens on first launch

<Steps>
  <Step title="A silent security check">
    This runs before any window appears. If it fails, a **Security Error** box
    appears and the app closes without opening. The usual cause is a debugger,
    proxy or traffic-analysis tool running on the Mac — close those and reopen.
  </Step>

  <Step title="The dependency check">
    If anything from the table above is missing, its screen appears now, over
    everything else.
  </Step>

  <Step title="The login screen">
    Or, if you have signed in on this Mac before, a brief blank moment and then
    straight to **Devices**.
  </Step>

  <Step title="Phone discovery starts">
    Anything plugged in appears within a few seconds. See
    [Connect your phones](/guides/connect-your-phones).
  </Step>
</Steps>

After sign-in the Companion has two screens: **Devices** and **Settings**. The
mascot button in the top bar opens **Sprout**, a side panel with an **Activity**
feed of what has gone wrong and a **Guides** tab of short walkthroughs.

## The one macOS permission prompt

The Companion asks for no privacy permissions. It does not want screen recording,
accessibility, your photos or your contacts, and it never asks for them.

There is exactly one prompt, and it is macOS's own: **a request for your Mac login
password**, needed to open the secure tunnel that iPhones on iOS 17 and newer
require. Type your password and click OK.

<Warning>
  Dismiss that prompt and the iPhone looks like it is not plugged in at all. The
  Companion says "Admin permission is required to start the iOS 17+ device
  tunnel. Please approve the password prompt and try again." Press **Build** or
  **Start** again and approve it this time.
</Warning>

iPhones on iOS 15 or 16 never trigger this prompt.

## Updates

There is no automatic update. The Companion checks its version when it launches
and when you sign in, and a required update is not a suggestion:

* A box titled **Update Required** appears — "A new version is available".
* The only button is OK.
* Pressing it **closes the app**.

To get going again, ask an owner for a fresh download link and install the new DMG
over the old one. Your license key still works.

While you are signed in and working, the Companion will not interrupt you with an
update notice. Updates only surface when you restart it or sign in again.

## What to read next

<CardGroup cols={2}>
  <Card title="Connect your phones" icon="mobile" href="/guides/connect-your-phones">
    Cable, Trust, and the first phone in the list.
  </Card>

  <Card title="WebDriverAgent" icon="wrench" href="/guides/wda-signing">
    Build, Start, Stop, and the two ways it gets signed.
  </Card>
</CardGroup>