Keycard: inyecta API keys sin variables de entorno

Keycard es una herramienta local-first para macOS que almacena y gestiona claves API sin tocar variables de entorno ni archivos de configuración dispersos. Inyecta secretos directamente en subprocesos usando XChaCha20-Poly1305 encryption, eliminando el riesgo de exposición accidental en git o en el shell. Funciona sin dependencia de cloud y es gratuita.

El problema real: secret sprawl y contaminación de shell

Ponele que trabajás en dos proyectos distintos. Uno usa OpenAI, el otro usa Anthropic. Abrís el terminal, necesitás las dos claves para probar, así que hacés export OPENAI_API_KEY=sk-... y export ANTHROPIC_API_KEY=sk-ant-.... Funciona en esa sesión. Cerrás la terminal. Al día siguiente te olvidás que estaban ahí, y cuando abris un nuevo tab, las variables siguen cargadas (spoiler: no deberían estar).

El problema se multiplica cuando tenés .env files en cada proyecto, plaintext en Notes, claves en .bash_profile o .zshrc, copypaste en el clipboard esperando que no te distraigas, y 10 lugares distintos donde debés cambiar la clave cuando la rotás.

Los números son preocupantes: según análisis de seguridad especializados, el 73% de los developers ha cometido un error de exposición de secretos al menos una vez. Un git add . mal pensado, un commit de .env, un screenshot sin ofuscar, y tus claves están públicas. GitHub escanea los repos cada segundo buscando secretos exactamente por esto.

La verdad es que la mayoría de las herramientas de gestión de secretos (Vault, 1Password, LastPass) están diseñadas para equipos empresariales y sync entre máquinas. Pero si trabajás solo o en un proyecto pequeño, toda esa infraestructura es overkill (que no es poco).

¿Qué es Keycard y cómo funciona?

Keycard es una aplicación macOS que resuelve esto con una arquitectura local-first. Según el sitio oficial, las claves viven encriptadas en tu máquina (~/Library/Application Support/Keycard/vault.db), no en cloud. Cuando necesitás una clave, la detecta desde tu clipboard (si copiaste una API key de OpenAI, identifica automáticamente que es OpenAI_API_KEY), la encripta con XChaCha20-Poly1305 (que es lo que USA Signal para mensajes end-to-end), y listo.

El flujo real es: ⌘⇧K en cualquier lado, pegás la clave, Keycard la encripta, no la tenés más en plaintext en el clipboard, y cuando la necesitás en un script, la inyecta donde debe ir sin exponer el shell. Lo explicamos a fondo en usando modelos avanzados de Claude.

La diferencia técnica acá es crítica. Cuando hacés export OPENAI_API_KEY=sk-..., esa variable queda en tu proceso shell y en todos los procesos hijos heredan automáticamente process.env. Cualquier comando que corras ve esa variable. Pero con Keycard, la clave vive solo en el subprocess específico que pediste, no en el shell ambiente (eso sí, es solo macOS por ahora, así que si usás Windows o Linux, no te cierra esto).

Inyección de secretos: la clave técnica que diferencia

El comando es simple: keycard run npm start. Lo que pasa por debajo es que Keycard:

• Abre el vault local (encriptado con tu contraseña de máquina)
• Decifra las claves que marcaste como “activas” para ese proyecto
• Crea un nuevo proceso hijo (subprocess) con esas variables en su process.env
• Ejecuta el comando (npm, python, etc.) dentro de ese proceso aislado
• Cuando termina, destruye el proceso. Las variables no quedan en tu shell.

Compará esto con el workflow tradicional: escribís las claves en .env, Node.js las carga con dotenv, las variables quedan en memoria el tiempo que vive el proceso. Si alguien hace un screenshot, un log dump, o un error no controlado que imprime process.env, ahí quedó expuesto todo. Con Keycard, las variables nunca tocan disco, nunca están en plain text en ningun lado.

Perfiles y ambientes: dev vs prod en un comando

Un caso real: trabajás en un proyecto que usa Claude, OpenAI, y Replicate. En development querés usar tus claves personales (para no quemar presupuesto). En producción usa las claves de la empresa (con cuota alta, facturación a cliente, todo controlado). Con .env traditionales, tenés que duplicar archivos, o armar un sistema casero con .env.local y .env.production, y acordarte cuál estás usando.

Con Keycard creás perfiles. El config es uno solo (en JSON o lo que sea), con mapeo de variables por perfil: Más contexto en arquitectura de los modelos de lenguaje.

• keycard run --profile dev npm start → carga OPENAI_API_KEY personal, REPLICATE_TOKEN personal
• keycard run --profile prod npm start → carga OPENAI_API_KEY de producción, REPLICATE_TOKEN de producción

Un solo comando, cambió todo. No copiaste, no pifiaste, no rotaste manualmente. El toggle es un flag.

Alternativas: Doppler, Vault, 1Password, y cuándo usarlas

¿La realidad? Keycard y Doppler resuelven 90% de los casos. Keycard si trabajás solo o en un proyecto chico y no te importa la rotación automática de claves. Doppler si tenés equipo, CI/CD, y necesitás que GitHub Actions o tu pipeline acceda a secretos sin hardcodearlos. Vault es para que se despierte sudando de noche el CISO. 1Password es el términomedio si no sos 100% tech.

Ahora bien, acá viene lo importante: la mayoría de developers sigue usando variables de entorno en plaintext, lo que significa que están un paso de un breach. Doppler cobra, pero te evita eso. Keycard es gratis pero solo local. Si tu situación es “trabajo solo, necesito protección básica, macOS”, Keycard te rescata.

Integración con Node.js y Python: ejemplos prácticos

La magia es que Keycard no hace nada especial. Las variables llegan como siempre via process.env (Node) u os.environ (Python). No necesitás cambiar código.

Node.js:

• Sin Keycard: npm install dotenv, luego require('dotenv').config(), luego const apiKey = process.env.OPENAI_API_KEY
• Con Keycard: keycard run npm start, y el código sigue siendo const apiKey = process.env.OPENAI_API_KEY. La diferencia es que la variable nunca estuvo en .env, vino inyectada.

Python:

• Sin Keycard: load_dotenv() desde python-dotenv, luego apiKey = os.getenv('OPENAI_API_KEY')
• Con Keycard: keycard run python main.py, el código es idéntico. os.getenv('OPENAI_API_KEY') devuelve el valor inyectado, no desde .env.

Entonces ¿por qué no simplemente usar Keycard para todo? Porque tiene limitaciones. Una, solo macOS (Windows y Linux están en roadmap pero no confirmado). Dos, si necesitás que tu CI/CD pipeline acceda a claves (GitHub Actions, Vercel, etc.), Keycard no sirve porque vive en tu máquina. Ahí necesitás Doppler o Vault.

Sincronización entre máquinas y backup seguro

Keycard el vault encriptado lo sincroniza vía iCloud por defecto. Eso significa que si tenés otro Mac, la bóveda se sincroniza automático (aunque encriptada, no en plaintext). Lo que no se sincroniza es el archivo .keycard de configuración de perfiles, así que si trabajás en dos máquinas, tenés que duplicar la config (inconveniente menor). Complementá con ejecutar LLMs en tu máquina local.

El backup es seguro porque el vault está encriptado. Incluso si alguien accede a tu iCloud backup, ve un archivo .db encriptado sin sentido. La clave maestra la tenés vos en tu máquina.

Ahora bien, esto plantea un problema de equipo: si trabajás solo está bárbaro. Pero si somos 5 developers en el mismo proyecto y necesitan todas acceder al mismo PROD_OPENAI_API_KEY, Keycard no escala. Eso es trabajo para Doppler o Vault, donde la rotación y los permisos son centralizados.

Mencionalo, pero en contexto local, si usás donweb.com para hosting tu aplicación, probablemente también necesites gestión de secretos en el servidor (vía variables de entorno en el panel de control o un secrets manager en el datacenter).

Errores comunes al usar gestión de secretos

1. Guardar secretos en el .gitignore pero olvidarse de que ya están en el git history

Escribiste export OPENAI_API_KEY=sk-... en un commit hace 3 meses. Ahora pusiste .env en .gitignore. Problema: el commit viejo sigue ahí público. Tenés que hacer un rebase destructivo o usar git filter-branch para limpiarlo. Con Keycard no existe este problema porque la clave nunca toca git.

2. Configurar múltiples ambientes pero mezclarlos en los comandos

Hiciste un script que usa dotenv y carga variables según NODE_ENV. Pero pusiste NODE_ENV=production en el .env, que es un archivo de source control. Resultado: tu local está usando claves de producción sin enterarte. Con Keycard, el perfil está separado del código, así que --profile dev nunca se confunde.

3. Dejar secretos en los logs o output de debug

Tu script crashea y imprime Error: connection failed with key ${apiKey}. Ahí quedó expuesto en el log. Parecería tonto, pero pasa todo el tiempo. Lo que no pasa es que imprimas una variable que no existe o que nunca tocaste en plaintext porque la inyectó Keycard. Ya lo cubrimos antes en integraciones seguras con APIs externas.

Preguntas Frecuentes

¿Cómo inyecta Keycard las claves si no tengo un archivo .env?

Keycard ejecuta tu comando (npm start, python main.py) en un subprocess con las claves en process.env (Node) u os.environ (Python). El código que escribe sigue siendo el mismo que leería de .env o de variables de entorno normales. La diferencia es que vienen inyectadas en tiempo de ejecución, no de un archivo.

¿Keycard funciona en Windows o Linux?

Hoy no. Keycard es solo macOS. El roadmap incluye Windows y Linux, pero no hay fecha confirmada. Si necesitás cross-platform ahora, Doppler funciona en cualquier SO.

¿Cuánto cuesta Keycard?

Gratis. No hay plan premium ni cloud. Podes donar o dar feedback, pero la herramienta no cuesta nada. El único trade-off es que es local-only, sin colaboración ni sync automático a servidores.

¿Keycard guarda mis claves en iCloud o algún cloud?

Según la documentación oficial, el vault vive localmente en tu máquina. Si activás sync en iCloud, se sincroniza el archivo encriptado (no plaintext), pero la clave maestra nunca sale de tu Mac. Si prefieres, podes desactivar el sync y dejar todo local.

¿Qué pasa si alguien accede a mi Mac y abre Keycard?

Keycard solicita autenticación (Face ID, Touch ID, o contraseña) cada vez que querés acceder a las claves. No te deja ver plaintext sin autorización. Pero si alguien tiene acceso físico a tu Mac desbloqueado y sabe tu contraseña, puede usar keycard run y extraer claves. Por eso, como cualquier secrets manager, la seguridad depende de que protejas tu máquina.

Conclusión

Keycard no es para todos. Si trabajás en equipo, necesitás CI/CD, o usás Windows/Linux, Doppler o Vault son mejores inversiones. Pero si sos un developer que odia el caos de .env duplicados, .bash_profile sucio, y el miedo constante de pushear un secret por accidente, Keycard es un ganador.

La gestión de secretos no tiene que ser complicada. Keycard demuestra que puede ser tan simple como ⌘⇧K, pegar tu clave, y olvidarse. Sin cloud, sin subscripciones, sin setup de 2 horas. Solo bajás la app, la configurás en 5 minutos, y escribís como siempre. La diferencia es que tus claves ya no están diseminadas por todos lados.

Fuentes

• Keycard — Local-first secret workflow for developers and AI teams
• Secret sprawl: cómo lidiar con los secretos dispersos en la infraestructura
• Do not use secrets in environment variables — here is how to do it better
• Doppler vs Vault: comparación de secrets managers
• OpenAI — Best practices for API key safety