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

# Meta Setup Agent

> Automated Business Manager structure setup with live login, checklist progress, and system-user handoff.

# Meta Setup Agent

The Meta Setup Agent helps clients and operators finish Business Manager structure work that Meta connect alone cannot do: create or link a Business Manager context, Page, ad account, and pixel, then hand off into Olympus's existing **system user token** connection.

## Where to start

1. Open **Settings → Integrations**.
2. On the Meta card, click **Set up Meta** (beside Connect / Manage).
3. Choose **Cloud browser** (no install) or **My browser** (desktop trust path).
4. Complete **live Meta login + 2FA** in Live View.
5. Click **I finished Meta login** — Olympus connects to the Browserbase session (CDP), opens the right Business Manager settings pages for anything missing, and updates the checklist.
6. Click **Re-check structure** after you finish each Live View task (or after connecting a system user token so Graph can detect assets).
7. When ready, use **Connect system token** — that completes the Setup Run and stores ad account / page / pixel IDs.

Deep link: `/settings/integrations?setup=meta`

## Dual execution modes

| Mode        | When to use                                                                                                    |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| **Cloud**   | Self-serve. Olympus opens a Browserbase session with optional Live View.                                       |
| **Desktop** | Higher trust. The playbook targets the user's real browser (macOS operator). Vault password is never required. |

Both modes share the same Setup Run state machine and playbook.

## Live login gate

Execution always requires a human in the loop for credentials and 2FA.

* Optional password storage may autofill only during a live run.
* Stored passwords **never** skip the login confirmation step.
* Live View is optional after login succeeds; the checklist remains the source of truth.

## Platform credential vault

Optional Meta passwords live in the **platform credential vault**, not Library Vault (files).

* Encrypted at rest with org-bound authenticated encryption.
* List APIs return metadata only (never plaintext).
* Retrieve is server-side only and access-logged.
* Revocable from the product without deleting Library media.

## System user handoff

Runtime Meta auth for v1 remains the existing system user token path:

* Setup Agent prepares structure + access posture.
* Operator or client pastes the system user token via the existing Connect modal.
* Ad account, page, and pixel IDs from the run merge into integration metadata when present.

OAuth is a parallel track and is not required for Setup Agent completion.

## Partial completion and support

When Meta blocks a step (payment method, identity verification, ambiguous multi-BM ownership):

1. Completed steps stay done.
2. The blocked step shows plain language + next action.
3. Other unblocked steps still finish.
4. **Notify support** creates a durable escalation with full run context (org, steps, blockers, IDs).

Only one active Meta Setup Run is allowed per organization.

## Environment

| Variable                                        | Purpose                     |
| ----------------------------------------------- | --------------------------- |
| `BROWSERBASE_API_KEY`                           | Cloud browser sessions      |
| `BROWSERBASE_PROJECT_ID`                        | Browserbase project         |
| `BROWSERBASE_API_BASE`                          | Optional API base override  |
| `ENCRYPTION_KEY` / `INTEGRATION_ENCRYPTION_KEY` | Credential vault encryption |

Without Browserbase credentials, a run can still start in degraded mode (checklist without Live View). Desktop mode does not require Browserbase.

## Fallback

If automation cannot finish, use the manual [Meta system user guide](/modules/integrations/meta).