← Portfolio · Case · Open source
zks: secrets for AI agents that never see them
An AI agent that provisions or rotates secrets normally reads every value it handles. zks inverts that: the agent edits a policy of names and destinations, and the values travel from source to provider without passing through its hands.
01The problem
Coding agents already install packages, run commands and edit files. The natural next step —provisioning an API key on Vercel, storing a token in GitHub Actions— hits a wall: any path that passes the value through the agent exposes it in logs, history and context. Giving it the whole Keychain is worse.
02How it works
The agent edits a policy file: names, sources and destinations, never values. zks resolves every value itself — 1Password, macOS Keychain, a hidden dialog, format-aware generators, templates, dotenv —, shows the human one native approval dialog per new destination, writes straight to the provider, and records metadata only in a hash-chained audit log that any tampering breaks. With zks run -- <command>, secrets are injected into a single child process, with a dialog every time.
03The destinations
Ten destinations: Vercel, AWS SSM Parameter Store, AWS Secrets Manager, GitHub Actions, Railway, Supabase, Netlify, Docker Swarm, Docker Compose secret files, and local .env files. System-wide install owned by root with tools pinned by sha256, plus an SBOM and npm audit on every installation.
04Web token capture
Tokens a provider issues on the web (clicking "generate API key") must enter the flow without the agent copying the value.
With zks capture inside ego-browser, a zks-built script moves the value from the page to the Keychain: the agent only sees lengths, and provider tokens are only captured from their pinned origins.
05Honest limits
The threat model is documented: it protects against the value traveling through the agent's context or logs, but a same-user agent could still read a page while it shows the value; zks shrinks that window (it clicks the reveal itself, blanks the field, leaves the page on about:blank) and cannot close it. macOS only, and it is not cryptographic zero-knowledge: the README says so.
06Result
Result
Release v1.0.0 (November 2026), Apache-2.0, 483 automated tests — including the suite of its own MCP stdio server that exposes zks to tool-calling agents — and CI on GitHub Actions. Built with ODD on Gentle Shell: specs, test-first, and AI code reviews whose CRITICAL findings were fixed before the release. Code: github.com/mauroociappinaph/zk-secrets .
More of the work: ← UNNA · ← Congreso Abierto · How I work with AI →