Pular para conteúdo

Variáveis de Ambiente

Referência completa de todas as variáveis de ambiente por surface.

Fonte de verdade: Doppler

As variáveis de cada ambiente (dev/staging/production) vivem no Doppler. Este documento é para visibilidade — não substitui o Doppler nem deve ser usado para criar .env manual.

Convenção de nomenclatura

As configurações usam pydantic-settings com env_nested_delimiter="__". Um fragmento aninhado vira um prefixo:

database: DatabaseFragment  →  DATABASE__URL, DATABASE__POOL_SIZE
agent: AgentFragment        →  AGENT__OPENAI_API_KEY, AGENT__RAG_EMBEDDING_MODEL

Campos de topo (sem fragmento) usam o nome da variável diretamente:

app_frontend_url  →  APP_FRONTEND_URL

App API (spryx-app-api)

Banco de dados

Variável Descrição Obrigatória Padrão
DATABASE__URL URL de conexão PostgreSQL Sim —
DATABASE__POOL_SIZE Tamanho do pool de conexões Não 20
DATABASE__MAX_OVERFLOW Conexões extras além do pool Não 10

Redis

Variável Descrição Obrigatória Padrão
REDIS__URL URL de conexão Redis Sim —

Autenticação JWT

Variável Descrição Obrigatória Padrão
AUTHENTICATION__ALGORITHM Algoritmo JWT (ex: RS256) Sim —
AUTHENTICATION__ISSUER Issuer do token Sim —
AUTHENTICATION__AUDIENCE Audience do token Sim —
AUTHENTICATION__PRIVATE_KEY Chave RSA privada (PEM) Sim —
AUTHENTICATION__PUBLIC_KEY Chave RSA pública (PEM) Sim —
AUTHENTICATION__LEEWAY Tolerância de clock em segundos Não 0
AUTHENTICATION__ACCESS_TOKEN_EXPIRE_MINUTES TTL do access token Não 15
AUTHENTICATION__REFRESH_TOKEN_EXPIRE_DAYS TTL do refresh token Não 30

Google OAuth

Variável Descrição Obrigatória Padrão
IDENTITY_OAUTH__CLIENT_ID Google OAuth client ID Sim —
IDENTITY_OAUTH__CLIENT_SECRET Google OAuth client secret Sim —

CORS

Variável Descrição Obrigatória Padrão
CORS__ALLOW_ORIGINS Lista de origens permitidas Sim —
CORS__ALLOW_CREDENTIALS Permite credenciais Não true
CORS__ALLOW_METHODS Métodos HTTP permitidos Não ["*"]
CORS__ALLOW_HEADERS Headers permitidos Não ["*"]

Rate Limit

Variável Descrição Obrigatória Padrão
RATE_LIMIT_TENANT__MAX_REQUESTS Máx. requisições por tenant por janela. 0 = desabilitado Sim —
RATE_LIMIT_TENANT__WINDOW_SECONDS Duração da janela (segundos) Não 60
RATE_LIMIT_IP__MAX_REQUESTS Máx. requisições por IP por janela (rotas core). 0 = desabilitado Sim —
RATE_LIMIT_IP__WINDOW_SECONDS Duração da janela (segundos) Não 60

OAuth Redirect (Connections)

Variável Descrição Obrigatória Padrão
AUTHENTICATION_OAUTH__ALLOWED_REDIRECT_DOMAINS Domínios permitidos em redirect URIs OAuth Não ["localhost", "127.0.0.1"]

Surface

Variável Descrição Obrigatória Padrão
APP_FRONTEND_URL URL do frontend do cliente Sim —
APP_API_BASE_URL URL base desta API (aceita também RAILWAY_PUBLIC_DOMAIN) Não http://localhost:8000
BACKOFFICE_FRONTEND_URL URL do frontend backoffice (para emails de impersonation) Não http://localhost:3001

Agent / RAG

Variável Descrição Obrigatória Padrão
AGENT__OPENAI_API_KEY Chave de API do OpenAI Sim —
AGENT__RAG_UNSTRUCTURED_API_KEY Chave da API Unstructured (parsing de documentos) Sim —
AGENT__RAG_UNSTRUCTURED_API_URL URL da API Unstructured Sim —
AGENT__RAG_EMBEDDING_MODEL Modelo de embedding Não text-embedding-3-large
AGENT__RAG_EMBEDDING_DIMS Dimensões do embedding Não 3072
AGENT__RAG_OPENAI_API_KEY_OVERRIDE Chave OpenAI alternativa para RAG Não null

Asset (S3)

Variável Descrição Obrigatória Padrão
ASSET__BUCKET_ACCESS_KEY_ID S3 access key ID Sim —
ASSET__BUCKET_SECRET_ACCESS_KEY S3 secret access key Sim —
ASSET__BUCKET_NAME Nome do bucket Sim —
ASSET__BUCKET_REGION Região do bucket Sim —
ASSET__BUCKET_ENDPOINT_URL Endpoint URL (S3 ou compatível) Sim —
ASSET__BUCKET_UPLOAD_URL_EXPIRES_IN Expiração de URLs de upload (segundos) Não 7200
ASSET__BUCKET_DOWNLOAD_URL_EXPIRES_IN Expiração de URLs de download (segundos) Não 3600

Billing (Stripe)

Variável Descrição Obrigatória Padrão
BILLING__STRIPE_SECRET_KEY Chave secreta do Stripe Sim —
BILLING__STRIPE_WEBHOOK_SECRET Segredo de assinatura de webhooks Sim —

Connections (Meta OAuth)

Variável Descrição Obrigatória Padrão
CONNECTIONS__META_CLIENT_ID Meta OAuth client ID Sim —
CONNECTIONS__META_CLIENT_SECRET Meta OAuth client secret Sim —

Messaging (WAHA / WhatsApp / Instagram / Slack)

Variável Descrição Obrigatória Padrão
MESSAGING__WAHA_BASE_URL URL base do WAHA Sim —
MESSAGING__WAHA_API_KEY Chave de API do WAHA Sim —
MESSAGING__WAHA_WEBHOOK_HMAC_KEY HMAC key para validação de webhooks WAHA Não null
MESSAGING__INSTAGRAM_CLIENT_ID Instagram/Meta client ID Não null
MESSAGING__INSTAGRAM_CLIENT_SECRET Instagram/Meta client secret Não null
MESSAGING__INSTAGRAM_VERIFY_TOKEN Token de verificação de webhook Instagram Não null
MESSAGING__WHATSAPP_CLIENT_ID WhatsApp client ID Não null
MESSAGING__WHATSAPP_CLIENT_SECRET WhatsApp client secret Não null
MESSAGING__WHATSAPP_VERIFY_TOKEN Token de verificação de webhook WhatsApp Não null
MESSAGING__WHATSAPP_BASE_URL URL base da WhatsApp API Não https://graph.facebook.com/v23.0
MESSAGING__SLACK_CLIENT_ID Slack client ID Não null
MESSAGING__SLACK_CLIENT_SECRET Slack client secret Não null
MESSAGING__SLACK_SIGNING_SECRET Slack signing secret Não null
MESSAGING__SPRYX_MESSAGE_API_URL URL interna da Message API Não http://localhost:8000
MESSAGING__SPRYX_AGENTS_API_URL URL interna da Agents API Não http://localhost:8000
MESSAGING__SPRYX_CLIENT_ID Spryx OAuth client ID Não null
MESSAGING__SPRYX_CLIENT_SECRET Spryx OAuth client secret Não null
MESSAGING__SPRYX_INTERNAL_AUTH_URL URL de auth interna Não http://localhost:8000

Notification (Resend)

Variável Descrição Obrigatória Padrão
NOTIFICATION__RESEND_API_KEY Chave de API do Resend Sim —
NOTIFICATION__RESEND_FROM_EMAIL Endereço de envio (noreply@...) Sim —

Observabilidade

Variável Descrição Obrigatória Padrão
LOGFIRE__TOKEN Token de acesso ao Logfire Não null (desabilitado)

E2E (somente em testes)

Ativam endpoints de auth programática usados exclusivamente em testes e2e. Nunca devem estar em staging ou produção.

Variável Descrição Obrigatória Padrão
E2E_ENABLED Habilita endpoints de auth e2e Não false
E2E_SECRET Segredo atual para auth e2e Não null
E2E_SECRET_PREVIOUS Segredo anterior (rotação) Não null

Backoffice API (spryx-backoffice-api)

Banco de dados

Variável Descrição Obrigatória Padrão
DATABASE__URL URL de conexão PostgreSQL Sim —
DATABASE__POOL_SIZE Tamanho do pool de conexões Não 20
DATABASE__MAX_OVERFLOW Conexões extras além do pool Não 10

Redis

Variável Descrição Obrigatória Padrão
REDIS__URL URL de conexão Redis Sim —

Autenticação JWT

Variável Descrição Obrigatória Padrão
AUTHENTICATION__ALGORITHM Algoritmo JWT (ex: RS256) Sim —
AUTHENTICATION__ISSUER Issuer do token Sim —
AUTHENTICATION__AUDIENCE Audience do token Sim —
AUTHENTICATION__PRIVATE_KEY Chave RSA privada (PEM) Sim —
AUTHENTICATION__PUBLIC_KEY Chave RSA pública (PEM) Sim —
AUTHENTICATION__LEEWAY Tolerância de clock em segundos Não 0
AUTHENTICATION__ACCESS_TOKEN_EXPIRE_MINUTES TTL do access token Não 15
AUTHENTICATION__REFRESH_TOKEN_EXPIRE_DAYS TTL do refresh token Não 30

Google OAuth

Variável Descrição Obrigatória Padrão
IDENTITY_OAUTH__CLIENT_ID Google OAuth client ID Sim —
IDENTITY_OAUTH__CLIENT_SECRET Google OAuth client secret Sim —

CORS

Variável Descrição Obrigatória Padrão
CORS__ALLOW_ORIGINS Lista de origens permitidas Sim —
CORS__ALLOW_CREDENTIALS Permite credenciais Não true
CORS__ALLOW_METHODS Métodos HTTP permitidos Não ["*"]
CORS__ALLOW_HEADERS Headers permitidos Não ["*"]

Rate Limit

Variável Descrição Obrigatória Padrão
RATE_LIMIT_IP__MAX_REQUESTS Máx. requisições por IP por janela. 0 = desabilitado Sim —
RATE_LIMIT_IP__WINDOW_SECONDS Duração da janela (segundos) Não 60

Surface

Variável Descrição Obrigatória Padrão
BACKOFFICE_FRONTEND_URL URL do frontend backoffice Sim —
BACKOFFICE_API_BASE_URL URL base desta API Não http://localhost:8001
BACKOFFICE_ALLOWED_EMAIL_DOMAIN Domínio de email permitido para login de staff Não spryx.ai

Asset (S3)

Variável Descrição Obrigatória Padrão
ASSET__BUCKET_ACCESS_KEY_ID S3 access key ID Sim —
ASSET__BUCKET_SECRET_ACCESS_KEY S3 secret access key Sim —
ASSET__BUCKET_NAME Nome do bucket Sim —
ASSET__BUCKET_REGION Região do bucket Sim —
ASSET__BUCKET_ENDPOINT_URL Endpoint URL (S3 ou compatível) Sim —
ASSET__BUCKET_UPLOAD_URL_EXPIRES_IN Expiração de URLs de upload (segundos) Não 7200
ASSET__BUCKET_DOWNLOAD_URL_EXPIRES_IN Expiração de URLs de download (segundos) Não 3600

Billing (Stripe)

Variável Descrição Obrigatória Padrão
BILLING__STRIPE_SECRET_KEY Chave secreta do Stripe Sim —
BILLING__STRIPE_WEBHOOK_SECRET Segredo de assinatura de webhooks Sim —

Notification (Resend)

Variável Descrição Obrigatória Padrão
NOTIFICATION__RESEND_API_KEY Chave de API do Resend Sim —
NOTIFICATION__RESEND_FROM_EMAIL Endereço de envio (noreply@...) Sim —

Observabilidade

Variável Descrição Obrigatória Padrão
LOGFIRE__TOKEN Token de acesso ao Logfire Não null (desabilitado)

Worker (spryx-worker)

Banco de dados

Variável Descrição Obrigatória Padrão
DATABASE__URL URL de conexão PostgreSQL Sim —
DATABASE__POOL_SIZE Tamanho do pool de conexões Não 20
DATABASE__MAX_OVERFLOW Conexões extras além do pool Não 10

Redis

Variável Descrição Obrigatória Padrão
REDIS__URL URL de conexão Redis Sim —

Autenticação JWT

Variável Descrição Obrigatória Padrão
AUTHENTICATION__ALGORITHM Algoritmo JWT (ex: RS256) Sim —
AUTHENTICATION__ISSUER Issuer do token Sim —
AUTHENTICATION__AUDIENCE Audience do token Sim —
AUTHENTICATION__PRIVATE_KEY Chave RSA privada (PEM) Sim —
AUTHENTICATION__PUBLIC_KEY Chave RSA pública (PEM) Sim —
AUTHENTICATION__LEEWAY Tolerância de clock em segundos Não 0
AUTHENTICATION__ACCESS_TOKEN_EXPIRE_MINUTES TTL do access token Não 15
AUTHENTICATION__REFRESH_TOKEN_EXPIRE_DAYS TTL do refresh token Não 30

Google OAuth

Variável Descrição Obrigatória Padrão
IDENTITY_OAUTH__CLIENT_ID Google OAuth client ID Sim —
IDENTITY_OAUTH__CLIENT_SECRET Google OAuth client secret Sim —

Surface

Variável Descrição Obrigatória Padrão
APP_API_BASE_URL URL da App API (para callbacks internos) Não http://localhost:8000
WORKER_TASK_SOFT_TIME_LIMIT Soft time limit de tasks Celery (segundos) Não 3300
WORKER_TASK_TIME_LIMIT Hard time limit de tasks Celery (segundos) Não 3600
WORKER_WORKERS Número de processos worker Não 2

Agent / RAG

Variável Descrição Obrigatória Padrão
AGENT__OPENAI_API_KEY Chave de API do OpenAI Sim —
AGENT__RAG_UNSTRUCTURED_API_KEY Chave da API Unstructured (parsing de documentos) Sim —
AGENT__RAG_UNSTRUCTURED_API_URL URL da API Unstructured Sim —
AGENT__RAG_EMBEDDING_MODEL Modelo de embedding Não text-embedding-3-large
AGENT__RAG_EMBEDDING_DIMS Dimensões do embedding Não 3072
AGENT__RAG_OPENAI_API_KEY_OVERRIDE Chave OpenAI alternativa para RAG Não null

Asset (S3)

Variável Descrição Obrigatória Padrão
ASSET__BUCKET_ACCESS_KEY_ID S3 access key ID Sim —
ASSET__BUCKET_SECRET_ACCESS_KEY S3 secret access key Sim —
ASSET__BUCKET_NAME Nome do bucket Sim —
ASSET__BUCKET_REGION Região do bucket Sim —
ASSET__BUCKET_ENDPOINT_URL Endpoint URL (S3 ou compatível) Sim —
ASSET__BUCKET_UPLOAD_URL_EXPIRES_IN Expiração de URLs de upload (segundos) Não 7200
ASSET__BUCKET_DOWNLOAD_URL_EXPIRES_IN Expiração de URLs de download (segundos) Não 3600

Connections (Meta OAuth)

Variável Descrição Obrigatória Padrão
CONNECTIONS__META_CLIENT_ID Meta OAuth client ID Sim —
CONNECTIONS__META_CLIENT_SECRET Meta OAuth client secret Sim —

Observabilidade

Variável Descrição Obrigatória Padrão
LOGFIRE__TOKEN Token de acesso ao Logfire Não null (desabilitado)