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:
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
envshed agent install
claude mcp add --transport http envshed https://app.envshed.com/api/mcp
claude mcp login envshed
- O
envshed agent installadiciona dois hooks e uma skill em~/.claude. Os hooks barram um prompt que contém um segredo e bloqueiam comandos que mostrariam um, comocat .envouenvshed secret get. A skill diz ao agente para usarenvshed requesteenvshed run. Veja Agent hooks. - O
claude mcp login envshedabre o navegador. Confira se ele cita o Claude Code e escolha Approve. Você também pode rodar/mcpdentro do Claude Code.
Reinicie o Claude Code se ele estava aberto. Para conferir a conexão:
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ó:
{
"mcpServers": {
"envshed": { "url": "https://app.envshed.com/api/mcp" }
}
}
O editor e o CLI do Cursor leem o mesmo arquivo. Para entrar pelo CLI:
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 installsó funciona com o Claude Code, então nada impede o Cursor de ler um arquivo.env. - O mascaramento não é automático. O
envshed runmascara a saída sozinho só quando o Claude Code o executa. No Cursor, peçaenvshed run --redact, como no prompt abaixo, ou definaENVSHED_AGENT_MODE=1no 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):
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:
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á:
| Arquivo | Quem lê |
|---|---|
AGENTS.md | Codex, Cursor, GitHub Copilot e outros agentes |
CLAUDE.md | Claude Code |
.cursor/rules/envshed.mdc | Cursor, como regra aplicada a todo chat (gravado quando o projeto tem uma pasta .cursor) |
.github/copilot-instructions.md | GitHub Copilot (quando o arquivo existe) |
GEMINI.md | Gemini 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:
## 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:
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:
- O agente chama
list_secret_keys. Ele recebe o nome de cada chave com um status,set,placeholder,disabledoumissing, e nenhum valor. - Para uma chave que não existe, ele chama
request_secrete 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. - O agente confere o pedido com
get_secret_request_statuse roda o app quando ele estiver preenchido. Se o app mostrar um segredo, a saída mostra um marcador no lugar do valor:
✔ 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:
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 setem 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 runmascara 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.envcom 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
scannão achar nada não prova que nada vazou.
Próximos passos
- Servidor MCP: todas as ferramentas, agentes hospedados e machine tokens.
- Sessões de agente: dê a um agente um acesso próprio, curto e limitado.
- Convidar o time.