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

# Ambiente

> Configuração de runtime para desenvolvimento local e implantações hospedadas.

# Ambiente

Esta página é a referência canônica de configuração de runtime para o repositório.

## Configuração local

Copie os arquivos de exemplo antes de iniciar o 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
```

## Variáveis do Supabase obrigatórias

* `NEXT_PUBLIC_SUPABASE_URL` para qualquer runtime que crie um client Supabase
* `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` para clients de navegador e com escopo de requisição
* `SUPABASE_SECRET_KEY` para acesso administrativo restrito ao servidor

## Variáveis Meta obrigatórias para envios reais e verificação de webhook

* `WHATSAPP_META_ACCESS_TOKEN` para o despacho de saída do lado do worker contra a Meta Graph API
* `WEBHOOK_SIGNATURE_SECRET` para validar `x-hub-signature-256` em webhooks de entrada
* `META_WEBHOOK_VERIFY_TOKEN` se você quiser uma verificação determinística do challenge no handshake de webhook da Meta

Essas variáveis de ambiente continuam válidas como fallback de bootstrap em nível de plataforma. Depois que um workspace armazena suas próprias credenciais de provedor via app do operador, os valores do workspace apoiados no Vault têm precedência.

## Aliases legados aceitos

O repositório ainda aceita estes enquanto as integrações estão sendo migradas:

* `NEXT_PUBLIC_SUPABASE_ANON_KEY`
* `SUPABASE_SERVICE_ROLE_KEY`

Novos trabalhos devem usar os nomes de chave publishable e secret.

## Alternância de modo de dados

* `WHATSAPP_PLATFORM_DATA_MODE=mock` mantém o app do operador, as rotas de API e os docs rodando contra o armazenamento tipado em memória
* `WHATSAPP_PLATFORM_DATA_MODE=supabase` habilita o caminho de dados apoiado no Supabase onde já está implementado

Se a variável for omitida, o repositório permanece em modo `mock` por padrão.

## Variáveis opcionais

* `SUPABASE_DB_URL` para ferramentas diretas de Postgres, migrações e jobs no lado do servidor que precisam da connection string. Também é necessária se você quiser que os segredos de provedor gerenciados pelo workspace sejam armazenados no Supabase Vault a partir da interface do produto.
* `WHATSAPP_META_API_VERSION` para sobrescrever a versão padrão da Graph API. O repositório usa `v25.0` por padrão.
* `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` como uma lista de e-mails separados por vírgula com permissão para inicializar acesso privilegiado ao workspace sem convite.
* `WORKSPACE_ALLOW_FIRST_CLAIM` para permitir que um único primeiro usuário reivindique a função de owner quando ainda não existem membros no workspace. O comportamento padrão é desabilitado, a menos que você defina explicitamente esse valor como `true`.
* `DEFAULT_WORKSPACE_SLUG` para inicializar o contexto de workspace padrão
* `DEFAULT_CHANNEL_WABA_ID`, `DEFAULT_CHANNEL_PHONE_NUMBER_ID`, `DEFAULT_CHANNEL_PHONE_E164` e `DEFAULT_CHANNEL_DISPLAY_NAME` para metadados de canal padrão

## Divisão de implantação

* `apps/web`, `apps/app` e `apps/api`, hospedados na Vercel, devem receber as variáveis públicas do Supabase de que precisam para seu caminho de runtime
* runtimes de servidor como `apps/api`, `apps/worker` e `apps/control-plane` também precisam de `SUPABASE_SECRET_KEY`
* `apps/worker` na Railway precisa de `WHATSAPP_META_ACCESS_TOKEN` para o despacho real ao provedor
* `apps/api` na Vercel precisa de `WEBHOOK_SIGNATURE_SECRET` para a ingestão de webhooks assinados na postura alpha atual
* somente runtimes de servidor devem receber `SUPABASE_DB_URL`
* o servidor do app do operador precisa de `SUPABASE_DB_URL` se você quiser que `/setup` e **Settings -> Provider** armazenem ou rotacionem segredos gerenciados pelo workspace
* o servidor do app do operador também precisa de `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` se você quiser que o caminho do primeiro operador privilegiado seja explícito, em vez de apenas por convite
* se um primeiro operador autenticado chegar em `/pending-access` com zero membros no workspace, recupere definindo `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS`, habilitando temporariamente `WORKSPACE_ALLOW_FIRST_CLAIM=true`, ou provisionando manualmente a linha em `workspace_members`; não é necessário excluir o usuário de autenticação
* `apps/control-plane` permanece no repositório, mas não faz parte do contrato atual do alpha hospedado, a menos que a decisão de ingress mude

## Próximos passos

* [Guia rápido](/pt-BR/quickstart)
* [Desenvolvimento](/pt-BR/development)
* [Arquitetura da plataforma](/pt-BR/platform/architecture)