Tu agente de IA puede leer tu .env: cómo proteger tus llaves
En la práctica/ 14 min de lectura
Tu agente de IA lee el .env sin pedir permiso. Tres medidas: una regla deny de Read, llaves de prueba en desarrollo y las reales solo en el gestor de secretos.
- IA
- Seguridad
- Claude Code
En este artículo (9)
Un agente de IA como Claude Code puede leer tu .env sin pedirte permiso: leer archivos del proyecto no requiere aprobación, y lo que lee entra en la conversación. Protégelo con tres medidas: una regla deny de Read para los archivos de secretos, llaves de prueba en desarrollo y las reales solo en el gestor de secretos de tu plataforma.
Aquí no repetimos lo que ya está escrito: la sintaxis completa de reglas vive en permisos de Claude Code en settings.json y el bloqueo desde la terminal en el hook para proteger tu .env. Este artículo junta las tres medidas, explica por qué .gitignore no te protege del agente y qué hacer si una llave ya se filtró. Revisado contra la documentación oficial el 19 de noviembre de 2026.
Por qué tu agente de IA puede leer el .env
Según la documentación de permisos de Claude Code, las herramientas de solo lectura, como leer un archivo o buscar con Grep, no piden aprobación dentro del directorio de trabajo. Comandos como cat, head o grep forman parte de un conjunto de solo lectura que corre sin preguntar en todos los modos. Tu .env está en el directorio de trabajo, así que para el agente leerlo es tan normal como leer package.json.
El modo auto tampoco lo frena. En la lista de lo que su clasificador permite por defecto, la documentación de los modos de permisos incluye leer el .env y enviar las credenciales a la API que les corresponde. Para el trabajo diario tiene sentido; para tus llaves significa que su valor entra en la conversación.
Y lo que entra en la conversación no se queda en tu pantalla. La página de uso de datos explica que Claude Code envía por la red los prompts y las respuestas del modelo, cifrados con TLS, y que guarda las transcripciones en texto plano en ~/.claude/projects/ durante 30 días por defecto (se ajusta con cleanupPeriodDays). Desde ahí, una llave también puede acabar en un archivo de prueba que el agente escribió, en un log o en un commit.
Desliza la figura para verla completa
Tampoco hace falta que el agente se equivoque. Basta una instrucción escondida en un README, un issue o una skill que instalaste: el agente la lee como parte del contexto y puede seguirla. Por eso conviene escanear una skill antes de instalarla, y por eso ninguna de las tres medidas depende de que el modelo se porte bien.
Bloquear la lectura con deny
La primera medida es una regla deny de Read para tus archivos de secretos. Va en .claude/settings.json, el archivo del proyecto que se sube al repo, así protege a todo el equipo:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"deny": [
"Read(.env)",
"Read(.env.*)",
"Read(!.env.example)",
"Read(*.pem)"
]
}
}
$schemale da a tu editor el esquema de SchemaStore, que marca una regla mal escrita, como un paréntesis sin cerrar. Valida la forma, no lo que la regla bloquea.permissions.denyes la lista de usos que Claude Code bloquea. Un deny gana en cualquier modo y desde cualquier archivo de configuración.Read(.env): un nombre de archivo suelto sigue la sintaxis de.gitignorey coincide a cualquier profundidad, así que bloquea el.envde la raíz y el deapps/web/.env.Read(.env.*)cubre.env.local,.env.productiony cualquier otra variante.Read(!.env.example)empieza con!: es una excepción que reabre la plantilla. Funciona porque va después de la regla que la bloquea y está en el mismo archivo; un!puesto primero no recorta nada. El agente necesita los nombres de las variables, no sus valores.Read(*.pem)bloquea certificados y llaves privadas en formato PEM, también a cualquier profundidad.
Qué cubre exactamente, según la documentación de permisos y la referencia de permissions.deny: las herramientas de archivos de Claude (Read, y como mejor esfuerzo Grep y Glob), las menciones con @, el contexto que comparte el IDE, los comandos de archivos que Claude Code reconoce en Bash, como cat, head, tail, sed y tee, y los destinos de redirecciones como < .env. Además, un deny de Read bloquea Edit y Write sobre la misma ruta.
Lo que no cubre, también según la documentación: un comando que lee archivos sin nombrarlos, como grep -r pattern ., ni un script de Python o de Node que abre el archivo por su cuenta. La documentación nombra comandos de Bash y no dice nada de Get-Content en PowerShell; en Windows, el hook PreToolUse cierra ese hueco. Para un bloqueo a nivel del sistema operativo, la documentación remite al sandbox, que limita lo que leen los comandos de shell y sus procesos. Funciona en macOS, Linux y WSL2; en Windows nativo, Claude Code corre los comandos sin sandbox. Y un detalle que confunde: un archivo .claudeignore no tiene ningún efecto.
Para cubrir todos tus proyectos, pon reglas con ruta absoluta en ~/.claude/settings.json: Read(//**/.env) y Read(//**/.env.*). Ahí la excepción no sirve: un ! solo recorta reglas relativas del mismo archivo, así que .env.example queda bloqueado en todos lados y ningún archivo de proyecto lo reabre. La sintaxis de rutas está explicada a fondo en el artículo de permisos.
Llaves de prueba en desarrollo
La regla deny reduce lo que el agente ve, pero tiene huecos documentados. La segunda medida hace que esos huecos importen poco: que en tu máquina no haya ninguna llave capaz de mover dinero o tocar datos reales. Si el agente lee una llave de prueba, lo peor que pasa es que rotas una llave sin clientes detrás.
Casi todos los proveedores separan los dos mundos. En Stripe, por ejemplo, cada entorno de prueba tiene sus propias claves, que empiezan con sk_test_, rk_test_ y pk_test_, mientras que las del modo activo empiezan con sk_live_, rk_live_ y pk_live_; los objetos de un modo no existen en el otro. También ofrece claves restringidas, con solo los permisos que tu código usa. Una regla práctica: si una llave de tu .env dice live o abre la base de datos de producción, no debería estar ahí. Para la base de datos, usa una copia local o un usuario de solo lectura, como en el MCP de Postgres de solo lectura.
Ojo con la plataforma donde despliegas. Según su documentación de variables, Railway pasa las variables del entorno vinculado a tu terminal con railway run y railway shell. Si tu carpeta está vinculada al entorno de producción y abres el agente dentro de railway shell, las llaves reales quedan en el entorno de cada comando que ejecute, y la regla deny no lo nota porque no hay archivo que leer. Vincula tu máquina a un entorno de desarrollo. Para lo que sí quede en el entorno, la variable CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 quita las credenciales que reconoce, por nombre o por valor, del entorno de los comandos, hooks y servidores MCP que lanza Claude Code (deja los tokens de GitHub).
Desliza la figura para verla completa
Llaves reales en el gestor de secretos
La tercera medida: las llaves de producción viven en un solo lugar, el gestor de secretos de la plataforma que corre tu app, y en ningún archivo. Tu servicio las recibe como variables de entorno al arrancar; ni tu disco ni tu repo las tienen. Dos ejemplos, descritos desde la documentación de cada plataforma:
- Railway. Las variables de cada servicio se definen en su pestaña Variables y llegan al build y al despliegue como variables de entorno; cada cambio queda pendiente hasta que lo revisas y despliegas. Una variable sellada (sealed) se entrega a builds y despliegues, pero no se ve en la interfaz, no se puede leer por la API y no se entrega con
railway runni conrailway variables. Sellarla no tiene vuelta atrás. - Google Cloud. Para Cloud Run, Google recomienda guardar llaves y contraseñas en Secret Manager y pasarlas como variable de entorno o como volumen. Las variables de entorno se resuelven al arrancar la instancia, así que Google recomienda fijar una versión del secreto en lugar de
latest. La identidad del servicio necesita el rolroles/secretmanager.secretAccessor.
Con las tres medidas, cada llave tiene un lugar y sabes qué pasa si se escapa:
| Llave | Dónde vive | ¿La ve el agente? | Si se filtra |
|---|---|---|---|
| Nombres de variables, sin valores | .env.example, en el repo | Sí, a propósito | Nada que rotar |
| Llave de prueba | .env.local en tu máquina, fuera de git | Bloqueada por deny, salvo por los huecos documentados | Rotas una llave sin datos reales |
| Llave real de producción | Gestor de secretos de la plataforma | No: solo la recibe el servicio desplegado | Rotación urgente |
Llave real en un .env local | Tu disco y, si el agente la leyó, la transcripción | Sí, en cuanto falla una barrera | Rotación urgente; no debería existir |
Desliza la figura para verla completa
.gitignore no basta
.gitignore le dice a git qué archivos dejar fuera de un commit. No es una regla para el agente: en Claude Code, el ajuste respectGitignore solo cambia lo que muestra el selector de archivos de @, no lo que puede leer la herramienta Read. Y en git tampoco cubre todo: la documentación de gitignore dice que los archivos que git ya rastrea no se ven afectados. Lo probamos en un repo desechable con git 2.54 y una llave falsa: un primer commit con el .env dentro y, después, .env en .gitignore.
$ git check-ignore -v .env
$ git check-ignore -v --no-index .env
.gitignore:1:.env .env
$ git ls-files .env
.env
$ git status --short
M .env
$ git rm --cached .env
rm '.env'
$ git commit -qm "stop tracking .env"
$ git log --oneline --all -- .env
<hash> stop tracking .env
<hash> first commit
$ git show HEAD~2:.env
PAYMENTS_SECRET_KEY=sk_test_FALSO_123
git check-ignore -v .envno imprime nada: para git, un archivo rastreado no está ignorado, aunque aparezca en.gitignore.- Con
--no-indexsí muestra la regla: el patrón existe, pero no se aplica a este archivo. git ls-filesconfirma que.envsigue en el índice.git statuslo marca como modificado: el siguientegit commit -asube el valor nuevo.git rm --cachedlo saca del índice sin borrarlo del disco, y el commit registra ese cambio.git log -- .envmuestra que el archivo sigue en dos commits del historial.git showrecupera la llave del primer commit. Cualquiera con una copia del repo puede hacer lo mismo.
Por eso la guía de GitHub para quitar datos sensibles pide, como primer paso, revocar o rotar el secreto; reescribir el historial viene después y a veces ni hace falta. Si te cuesta ver qué entra en cada commit cuando trabaja el agente, revisa el flujo de git para trabajar con agentes de IA.
Qué hacer si una llave se filtró: rotarla
Una llave que el agente leyó está en la transcripción local y viajó en una petición al modelo. Una que llegó a un commit está en cada clon. En ningún caso se puede "desleer": se rota. Los pasos generales, con el orden para una llave que mueve dinero, están en variables NEXT_PUBLIC_ y secretos. Aquí va la parte que cambia con un gestor de secretos, en el caso de Secret Manager y Cloud Run (los números de versión son ilustrativos):
# 1. Add the new key as a new version, read from standard input
gcloud secrets versions add PAYMENTS_KEY --data-file=-
# 2. Point the service at that version; this deploys a new revision
gcloud run services update my-service \
--update-secrets=PAYMENTS_SECRET_KEY=PAYMENTS_KEY:2
# 3. When the new revision serves traffic, disable the old version
gcloud secrets versions disable 1 --secret=PAYMENTS_KEY
versions addcrea la versión 2 del secreto. Con--data-file=-, gcloud lee el valor de la entrada estándar, así no lo dejas en un archivo.services updatecon--update-secretscambia la variable de entorno a la versión 2. Como el valor se resuelve al arrancar la instancia, hace falta esta revisión nueva; la revisión anterior sigue con la llave vieja.versions disableapaga la versión 1 en Secret Manager. Se puede volver a activar conversions enablesi algo falla.
Los comandos salen de la documentación de Google (agregar una versión del secreto y la de Cloud Run de arriba) y los revisamos con la ayuda local de Google Cloud SDK 581.0.0; no los ejecutamos contra un proyecto. Deshabilitar la versión vieja en Secret Manager no invalida la llave: eso solo lo hace el proveedor. El orden completo:
- Crea la llave nueva en el proveedor. En Stripe, "rotar" revoca la clave y crea la de reemplazo; si eliges un vencimiento futuro, las dos funcionan hasta 7 días. Si la llave se filtró, elige vencimiento inmediato.
- Guárdala en el gestor de secretos: los comandos de arriba, o en Railway editas la variable y despliegas el cambio pendiente.
- Comprueba que la app funciona con la llave nueva.
- Revoca la llave vieja en el proveedor. Es el paso que cierra la filtración.
- Revisa los registros del proveedor desde el día en que la llave pudo salir.
- Cierra la puerta por donde salió: la regla deny, la llave real fuera de tu
.envy fuera de cualquier archivo o commit que el agente haya escrito. La transcripción local la conserva hasta que se limpia; por eso se rota y no basta con borrar.
Errores comunes
- Contar con
.gitignorepara frenar al agente. Solo afecta a git y al selector de@; la herramienta Read lo ignora. - Poner la excepción antes de la regla.
Read(!.env.example)listado primero no recorta nada. - Escribir
Write(.env)oGrep(.env)en deny. Las reglas con ruta solo se comparan conReadyEdit; esas no bloquean nada. - Crear un
.claudeignore. No tiene efecto; pasa sus entradas a reglas deny deRead. - Dejar llaves
liveen el.env"solo para probar". Es justo la llave que no quieres en una transcripción. - Abrir el agente dentro de
railway shellvinculado a producción. Las llaves quedan en el entorno, donde la regla deny no mira. - Borrar el archivo o reescribir el historial en vez de rotar. La llave sigue en clones, transcripciones y logs.
- Dar por hecho el sandbox en Windows. En Windows nativo los comandos corren sin sandbox; necesitas WSL2.
Preguntas frecuentes
¿La regla deny impide que el agente ejecute cat .env?
Sí. La documentación dice que los deny de Read se aplican a los comandos de archivos que Claude Code reconoce en Bash, como cat, head, tail, sed y tee, y a redirecciones como < .env. No se aplican a grep -r sobre la carpeta ni a un script que abre el archivo por su cuenta.
¿Basta con escribir en CLAUDE.md que no lea el .env?
No. Según la documentación de memoria, Claude trata CLAUDE.md como contexto, no como configuración obligatoria. La de los modos de permisos lo dice directo: para una garantía firme, agrega una regla deny.
¿El agente puede usar mis llaves sin leer el archivo?
Sí, si están en el entorno de la terminal donde lo abriste: exportadas, o cargadas con railway run o railway shell. Ahí la regla deny no aplica. Usa llaves de prueba en local y CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 para quitarlas del entorno de los comandos.
¿Tengo que rotar una llave de prueba que el agente leyó?
Conviene, y cuesta poco: no tiene clientes detrás, así que la rotas sin prisa y sin riesgo. Esa es la ventaja de tener solo llaves de prueba en tu máquina. Si fue una llave real, la rotación es urgente.
Checklist
.claude/settings.jsontieneRead(.env),Read(.env.*)y la excepción para.env.example, en ese orden.~/.claude/settings.jsonbloquea//**/.envsi quieres cubrir todos tus proyectos.- En Windows, el hook PreToolUse cubre PowerShell.
- El
.envlocal solo tiene llaves de prueba o de solo lectura. - Tu carpeta está vinculada a un entorno de desarrollo, no al de producción.
- Las llaves reales viven en el gestor de secretos, selladas o con versión fija.
git ls-filesno muestra ningún.env, ygit log --all -- .envestá vacío.- Sabes cómo rotar cada llave y dónde ver sus registros.
Las reglas deny son una parte de la configuración de permisos. Para el resto, como allow y ask, revisa permisos de Claude Code en settings.json.
¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.
Escrito por

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026