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

# Quickstart

> Get up and running with Switchbord — hosted or local contributor setup.

## Option A — Hosted (app.switchbord.ai)

If you are an operator joining an existing team or starting a new workspace on the hosted platform:

1. Sign up at [app.switchbord.ai](https://app.switchbord.ai).
2. Create a workspace (or accept an invite from an existing workspace admin).
3. Go to **Settings → Provider** and connect your Meta Business account and WhatsApp phone number.
4. Follow the [Connect WhatsApp](/platform/connect-whatsapp) guide for the full credential setup walkthrough.

If you were invited to a workspace and land on `/pending-access`, your invite is still processing. Contact your workspace admin.

***

## Option B — Local contributor setup

### Install

```bash theme={null}
pnpm install
```

### Validate the workspace

```bash theme={null}
pnpm lint
pnpm docs:lint
pnpm typecheck
pnpm test
```

### Configure environment files

Copy the example files before starting the workspace:

```bash theme={null}
cp apps/app/.env.example apps/app/.env.local
cp apps/api/.env.example apps/api/.env.local
cp apps/web/.env.example apps/web/.env.local
```

If you are working on worker or webhook-runtime behavior, also seed:

```bash theme={null}
cp apps/worker/.env.example apps/worker/.env.local
```

<Note>
  `apps/control-plane` has been removed. Do not create a `.env.local` for it.
</Note>

#### Minimum Supabase variables

* `NEXT_PUBLIC_SUPABASE_URL`
* `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`
* `SUPABASE_SECRET_KEY` — for server-side admin paths
* `WHATSAPP_PLATFORM_DATA_MODE=supabase` — only for surfaces with a real Supabase-backed implementation
* `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` — recommended for any shared or hosted environment to set the first privileged operator
* `WORKSPACE_ALLOW_FIRST_CLAIM=true` — only for intentional one-time first-user owner claim during local bootstrap

The repo still accepts `NEXT_PUBLIC_SUPABASE_ANON_KEY` and `SUPABASE_SERVICE_ROLE_KEY` as legacy aliases, but new setup should use the publishable key and secret key forms.

#### Minimum Meta variables (for a real webhook-plus-send loop)

* `WHATSAPP_META_ACCESS_TOKEN` — for the worker
* `WEBHOOK_SIGNATURE_SECRET` — for `apps/api`
* `META_WEBHOOK_VERIFY_TOKEN` — for explicit webhook challenge verification
* `SUPABASE_DB_URL` — if using Supabase Vault for workspace-managed provider secrets

If a signed-in user is not yet provisioned into a workspace, the operator app routes them to `/pending-access` until an invite is accepted or bootstrap rules grant membership.

If the first local operator gets stranded on `/pending-access`, do not delete the auth user. Fix bootstrap by setting `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS`, temporarily enabling `WORKSPACE_ALLOW_FIRST_CLAIM=true`, or manually inserting the missing `workspace_members` row.

See [Environment](/environment) for the full runtime configuration contract.

### Start the workspace

```bash theme={null}
pnpm dev
```

### Local ports

* app: `3000`
* web: `3001`
* api: `3002`
* docs: `3004`
* storybook: `6006`
* worker: background process, no HTTP port

### High-value routes

* operator inbox: `http://localhost:3000/inbox`
* runtime diagnostics: `http://localhost:3000/runtime`
* API readiness: `http://localhost:3002/ready`
* OpenAPI spec: `http://localhost:3002/spec`
* Meta webhook ingress: `http://localhost:3002/webhooks/meta`

### Working assumptions

* feature flags default to `on`
* the Supabase env contract must be satisfied before any surface uses Supabase directly
* forward-only migration is the active posture
* historical message migration is intentionally out of scope for the first cut

## Read next

* [Connect WhatsApp](/platform/connect-whatsapp)
* [Webhook Setup](/platform/webhook-setup)
* [Contributing](/contributing)
* [Contributor Architecture](/contributing/architecture)
* [Environment](/environment)