Pular para o conteúdo principal

Comece com IA

Este guia prepara um agente de código, o Claude Code ou o Cursor, para trabalhar num projeto com o Envshed. No fim, o agente roda o seu app com os segredos e pede a você uma chave que estiver faltando. Os valores ficam fora do chat.

Leva uns dez minutos. Os passos 1 e 2 são feitos uma vez por máquina, e o passo 4 uma vez por projeto.

:::info Antes de começar Você precisa de uma conta no Envshed (o primeiro acesso cria a conta: Comece grátis), do Node.js 20.12 ou mais recente e do Claude Code ou do Cursor. Testado com o Claude Code 2.1.323 e o Cursor CLI 2026.11.13. :::

1. Instale o CLI e entre na sua conta​

Rode isto no seu próprio terminal, não no agente:

terminal
npm install -g envshed
envshed login

O envshed login abre o navegador e mostra um código. Confira se o navegador mostra o mesmo código e escolha Approve sign-in. Os comandos envshed do agente usam esse login, com as suas permissões.

2. Conecte o agente​

Claude Code​

terminal
envshed agent install
claude mcp add --transport http envshed https://app.envshed.com/api/mcp
claude mcp login envshed
  • O envshed agent install adiciona dois hooks e uma skill em ~/.claude. Os hooks barram um prompt que contém um segredo e bloqueiam comandos que mostrariam um, como cat .env ou envshed secret get. A skill diz ao agente para usar envshed request e envshed run. Veja Agent hooks.
  • O claude mcp login envshed abre o navegador. Confira se ele cita o Claude Code e escolha Approve. Você também pode rodar /mcp dentro do Claude Code.

Reinicie o Claude Code se ele estava aberto. Para conferir a conexão:

terminal
claude mcp get envshed

Ele mostra Status: ✔ Connected.

Cursor​

Adicione o servidor em ~/.cursor/mcp.json, para todos os projetos, ou em .cursor/mcp.json, para um projeto só:

~/.cursor/mcp.json
{
"mcpServers": {
"envshed": { "url": "https://app.envshed.com/api/mcp" }
}
}

O editor e o CLI do Cursor leem o mesmo arquivo. Para entrar pelo CLI:

terminal
cursor-agent mcp login envshed
cursor-agent mcp list-tools envshed

O segundo comando lista 10 ferramentas, como list_secret_keys e request_secret. Use uma versão atual do Cursor. O Cursor CLI de setembro de 2025 pede um escopo que o Envshed não emite, e o login para com "This connection can't continue".

Duas coisas funcionam diferente no Cursor:

  • Não há hooks. O envshed agent install só funciona com o Claude Code, então nada impede o Cursor de ler um arquivo .env.
  • O mascaramento não é automático. O envshed run mascara a saída sozinho só quando o Claude Code o executa. No Cursor, peça envshed run --redact, como no prompt abaixo, ou defina ENVSHED_AGENT_MODE=1 no ambiente do terminal do Cursor.

3. Traga um projeto​

Um projeto que já tem arquivos .env: deixe o agente movê-los. Veja Migrar com um agente. O agente cria o projeto, importa cada arquivo pelo nome das chaves e nunca lê um valor.

Um projeto novo: na pasta do projeto, troque <org> pelo slug da sua organização (o envshed orgs lista as suas):

terminal
envshed project create --name my-app -o <org>
envshed init -o <org> -p my-app -e development --yes --no-guide --no-import

O init grava o .envshed.json, que só tem nomes e pode ir para o git. Adicione os valores que você já tem no painel, ou no seu terminal com envshed secret set API_KEY -e development, que pede o valor sem mostrá-lo na tela. Deixe de fora os que você ainda não tem: o agente pede esses no próximo passo.

4. Faça disso uma regra​

Grave uma regra no projeto para que todo agente que abrir este repositório use o Envshed para os segredos, sem você repetir isso em cada prompt. Na pasta do projeto:

terminal
envshed agent rules

Ele mostra os arquivos e o texto e pergunta antes de gravar. A regra entra entre marcadores, e o resto de cada arquivo fica como está:

ArquivoQuem lê
AGENTS.mdCodex, Cursor, GitHub Copilot e outros agentes
CLAUDE.mdClaude Code
.cursor/rules/envshed.mdcCursor, como regra aplicada a todo chat (gravado quando o projeto tem uma pasta .cursor)
.github/copilot-instructions.mdGitHub Copilot (quando o arquivo existe)
GEMINI.mdGemini CLI (quando o arquivo ou uma pasta .gemini existe)

Passe --all para gravar todos os arquivos e --yes para gravar sem terminal. Rodar de novo não muda nada, a não ser que a regra tenha mudado. O envshed init mostra esse comando como dica quando termina, e o envshed init --agent-rules grava a regra durante a configuração. Faça commit dos arquivos: eles não têm nenhum segredo, e o agente de cada pessoa do time recebe a regra.

O CLI grava a regra em inglês, que todos esses agentes entendem. Para pôr à mão, cole isto no arquivo de instruções do seu agente:

markdown
## Segredos (Envshed)

Este projeto guarda os segredos no Envshed. Ao trabalhar aqui:

- Nunca leia, mostre ou copie arquivos `.env` ou qualquer valor de segredo, e nunca peça ao usuário para colar um valor no chat.
- Rode comandos que precisam de segredos com `envshed run --redact -- <comando>`, por exemplo `envshed run --redact -- npm run dev`. O processo recebe os valores; a saída fica mascarada.
- Para ver quais chaves existem, use a ferramenta MCP `list_secret_keys` ou `envshed definition list`. Os dois mostram nomes, nunca valores.
- Se faltar uma chave, peça com `envshed request <KEY> --reason "<motivo>"` (ou a ferramenta MCP `request_secret`) e espere uma pessoa preencher.
- Para mover um arquivo `.env` para o Envshed, use `envshed import`. Não copie valores à mão.
- Se o `envshed` não estiver instalado, use `npx envshed@latest` no lugar dele.

:::caution Uma regra é uma instrução, não uma barreira O agente ainda pode ignorá-la. A barreira vem dos hooks do Claude Code (envshed agent install) e do que o servidor permite a cada papel e a cada token. :::

5. Dê uma tarefa ao agente​

Cole isto no agente, com a sua organização, o seu projeto e o seu comando de início:

output
Rode este app com o Envshed. Organização: <org>. Projeto: my-app. Ambiente: development.
1. Use o servidor MCP do Envshed para listar os nomes das chaves e achar as que estão faltando.
2. Para cada chave que faltar, chame request_secret, me passe o link e espere eu preencher.
3. Rode o app com: envshed run -- npm start
Nunca leia arquivos .env, nunca mostre valores de segredos e nunca me peça para colar um valor no chat.

No Cursor, escreva envshed run --redact -- npm start no passo 3.

O que acontece:

  1. O agente chama list_secret_keys. Ele recebe o nome de cada chave com um status, set, placeholder, disabled ou missing, e nenhum valor.
  2. Para uma chave que não existe, ele chama request_secret e passa a você um link para o painel. Você digita o valor nessa página. Ele vai para o Envshed, não para o chat.
  3. O agente confere o pedido com get_secret_request_status e roda o app quando ele estiver preenchido. Se o app mostrar um segredo, a saída mostra um marcador no lugar do valor:
output
✔ Loaded 3 secrets
Masking 3 secret values in output, 0 too short or common to mask. Output is piped, so the command may drop colors.

Starting agent-demo with config:
DATABASE_URL=[ENVSHED:DATABASE_URL]
PAYMENTS_API_KEY=[ENVSHED:PAYMENTS_API_KEY]
EMAIL_API_KEY=[ENVSHED:EMAIL_API_KEY]

Você também pode pedir uma chave por conta própria, de qualquer terminal: envshed request EMAIL_API_KEY --reason "enviar e-mail". Veja Pedidos de segredo.

6. Confira o histórico com o scan​

O envshed scan procura no histórico local do agente os valores do seu cofre e formatos de token conhecidos, como chaves do Stripe ou do GitHub. Ele nunca mostra um valor. Rode na pasta do projeto:

terminal
envshed scan

Depois dos passos acima, ele mostra Nothing found. Se achar algo, lista a chave, o arquivo e a data, sai com código 2 e mostra os comandos para fazer a rotação. Troque o que ele achar: o agente pode já ter mandado o valor ao provedor do modelo.

Por padrão, o scan lê o histórico do Claude Code. Para outros arquivos, passe --path <arquivo ou pasta>. Veja Varrer históricos de agentes.

Teste com o projeto de demonstração​

O envshed/agent-demo é um app pequeno com três segredos falsos que mostra a configuração ao iniciar. O README dele passa por estes passos em uns cinco minutos e depois roda o app com um arquivo .env e com envshed run. O envshed scan acha os valores na primeira saída e nada na segunda.

O que o Envshed garante, e o que não garante​

Isto vale em todos os planos:

  • O servidor MCP nunca devolve nem aceita um valor. As ferramentas lidam com nomes de chaves e status. Um teste falha se uma ferramenta ganhar um campo que possa guardar um valor.
  • Um valor pedido nunca passa pelo chat. Uma pessoa digita o valor no painel ou com envshed secret set em outro terminal.
  • O agente não recebe mais do que o seu papel. As chamadas MCP seguem as mesmas permissões da API e vão para o log de auditoria com o nome do cliente.
  • No Claude Code, o envshed run mascara os valores conhecidos no stdout e no stderr, como [ENVSHED:KEY_NAME], sem nenhuma flag.

Isso reduz vazamentos acidentais. Não é uma barreira contra um agente com acesso ao shell:

  • O agente alcança o que o seu login alcança. Ele poderia rodar envshed secret get, mostrar o próprio ambiente ou copiar o .env com outro nome e ler a cópia. Os hooks bloqueiam os caminhos comuns no Claude Code, e o Cursor não tem hooks. Limites que precisam valer, como quem lê produção, ficam no servidor: use papéis e service tokens com escopo.
  • O mascaramento compara os valores como eles são. Um valor cortado em pedaços, codificado de outro jeito, gravado num arquivo ou enviado pela rede não é mascarado. Veja o que é mascarado.
  • Um valor que você cola no chat fica na transcrição. O hook do prompt impede que ele chegue ao modelo, mas o Claude Code ainda o grava em arquivos locais. Faça a rotação.
  • Os nomes das chaves entram no contexto do modelo. O Envshed não trata nomes de chaves como segredo.
  • O scan não achar nada não prova que nada vazou.

Próximos passos​