O que são variáveis de ambiente e secrets? Um guia simples

Uma variável de ambiente é uma configuração com nome — como DATABASE_URL ou STRIPE_SECRET_KEY — que é entregue ao seu app quando ele roda, em vez de ser escrita dentro do código. Um secret é uma variável de ambiente cujo valor precisa ficar privado: uma chave de API, uma senha, uma chave de assinatura. Manter esses valores fora do código permite trocá-los sem editar o app, usar valores diferentes para testes e para clientes reais e evitar que vazem quando você compartilha ou publica o seu código.

Por que isso importa ao construir com IA

No momento em que o seu app faz algo útil com outro serviço — recebe um pagamento, envia um e-mail, chama um modelo de IA — ele precisa de uma chave. Os construtores de apps com IA pedem essas chaves com frequência, e o lugar onde a chave acaba decide se o seu app está seguro.

Dois problemas são comuns em apps feitos com IA:

• A chave é colada no chat ou no código. Ela passa a existir no histórico do chat, nos arquivos do projeto e em qualquer exportação ou repositório. Quem a vê pode usar a sua conta.
• A chave é usada no navegador. Se o código que chama a Stripe ou a OpenAI roda na página, a chave é enviada para todos os visitantes. As pessoas olham, e scanners automáticos procuram chaves expostas o tempo todo.

Entender variáveis de ambiente permite identificar os dois problemas e pedir a correção.

Uma analogia do dia a dia: o cofre do hotel

O código do seu app é como o quarto do hotel. Hóspedes (e faxineiros, e qualquer pessoa com o cartão de acesso) passam por ele. Você não deixaria o seu passaporte em cima da mesa.

As variáveis de ambiente são o cofre do quarto. O quarto sabe que existe um cofre e como abri-lo quando preciso, mas o passaporte não fica largado por aí. E se você mudar de quarto — do seu ambiente de teste para o seu site no ar — coloca outro passaporte no cofre desse quarto, sem redecorar nada.

Como funciona

O seu código se refere a um nome, não a um valor. Em JavaScript no servidor, isso aparece como process.env.STRIPE_SECRET_KEY. Quando o app inicia, a plataforma onde ele roda preenche o valor daquele nome. Você altera o valor nas configurações da plataforma, reinicia ou publica de novo, e o app passa a usar o novo valor — sem mudar o código.

De onde vêm os valores depende de onde o app roda:

Variáveis públicas e secretas

Nem toda variável de ambiente é secreta. Vale separá-las em dois grupos:

Os frameworks web tornam essa separação explícita. No Vite, só entram no código do navegador as variáveis cujo nome começa com VITE_; no Next.js, o prefixo é NEXT_PUBLIC_. Isso é um recurso de segurança: tudo o que tem esses prefixos acaba nos arquivos que todo visitante baixa, então um secret nunca deve receber um deles.

Um exemplo prático: um botão de resumo com IA

Você quer um botão “Resumir esta nota” que chama um modelo de IA.

A versão insegura: o código do botão, rodando no navegador, chama o provedor de IA diretamente, com a chave de API escrita dentro dele. Funciona na prévia. Mas significa que qualquer pessoa pode abrir as ferramentas de desenvolvedor do navegador, copiar a chave e gerar uma conta alta na sua conta.

A versão segura:

1. Você cria a chave no provedor de IA e a guarda como um secret chamado OPENAI_API_KEY (ou similar) nas configurações do projeto.
2. O backend ganha uma rota, POST /api/summarise, que lê process.env.OPENAI_API_KEY, verifica se o usuário está logado e chama o provedor.
3. O botão chama a sua rota, não o provedor. O navegador nunca vê a chave.
4. Você adiciona o mesmo secret nas configurações do app publicado e publica de novo, para que o site no ar também o tenha.

Esse padrão — o navegador chama o seu servidor, e o seu servidor guarda a chave e chama o serviço — vale para pagamentos, e-mail, mapas e qualquer outra API paga. O guia sobre como usar APIs de LLM aprofunda o caso da IA.

Termos-chave

• Arquivo .env: um arquivo de texto com linhas NOME=valor, usado no desenvolvimento local. Inclua-o no .gitignore para que não seja enviado ao git.
• .env.example: uma cópia só com os nomes, sem valores reais, enviada ao repositório para que outras pessoas saibam quais variáveis configurar.
• Rotacionar: substituir um secret por um novo e revogar o antigo.
• Escopo / permissões: muitos provedores permitem criar chaves que só fazem certas coisas. Uma chave que só envia e-mails é menos perigosa do que uma que faz tudo.
• Chaves de teste vs. chaves de produção: provedores como a Stripe dão chaves separadas para teste e para dinheiro real. Use as chaves de teste até lançar.
• Signing secret (segredo de assinatura): um secret usado para verificar que uma mensagem, como um webhook, realmente veio do remetente.

Erros comuns e ideias erradas

• “Meu repositório é privado, então chaves nele estão tudo bem.” Repositórios privados são compartilhados, copiados (fork), exportados e clonados para notebooks. As chaves continuam não pertencendo ali. Se você conectar um projeto ao GitHub, confira se nenhum arquivo .env foi incluído.
• “Eu apaguei, então sumiu.” O git guarda o histórico, e os logs do chat guardam as mensagens. Se uma chave já foi exposta, rotacione-a.
• Usar um prefixo público em um secret. VITE_OPENAI_KEY coloca a sua chave no bundle do navegador.
• Esquecer de publicar de novo. Mudar uma variável nas configurações normalmente só tem efeito depois que o app reinicia ou é publicado novamente.
• Uma chave só para tudo. Chaves separadas para teste e produção, e por app, permitem revogar uma sem quebrar as outras.
• Nenhum limite de gastos. Para APIs pagas, defina um orçamento ou limite no painel do provedor, caso uma chave vaze.

O que pedir ao seu construtor de IA

• “Leia a chave secreta da Stripe de uma variável de ambiente chamada STRIPE_SECRET_KEY. Use-a somente no servidor.”
• “Garanta que nenhum secret seja usado no código do cliente nem receba o prefixo VITE_ / NEXT_PUBLIC_.”
• “Crie um .env.example listando todas as variáveis que o app precisa, sem valores, e garanta que .env esteja no git-ignore.”
• “Verifique os arquivos do frontend já compilados em busca de qualquer texto que pareça uma chave de API.”

Nosso checklist de segurança para apps feitos com IA cobre os secrets junto com as outras verificações que valem a pena antes do lançamento.

Secrets no Mythex

No Mythex, os secrets são variáveis de ambiente do projeto, injetadas tanto na sandbox da prévia quanto no seu app publicado. Você os adiciona em configurações do projeto → Secrets ou com /secrets no chat, e quando o agente precisa de uma chave ele mostra um cartão de secrets no chat, para que o valor seja digitado em um campo de formulário e não apareça na transcrição da conversa. Se você alterar um secret de um app no ar, publique de novo para que o deploy o use. As exportações do projeto deixam os secrets de fora, e arquivos .env importados são removidos, para que você os adicione de novo nas configurações. Veja variáveis de ambiente e secrets e secrets no chat na documentação.

Perguntas