q-ringOpen-source OS keychain manager for AI coding agents
A free CLI and MCP server that keeps API keys in your operating system's keychain and hands them to Cursor, Claude Code, and Kiro on request. Nothing leaves your machine — no cloud, no account, no .env file.
$ pnpm add -g @i4ctime/q-ring
Open source, by the numbers
Everything ships in the box
Works everywhere
Drop into your AI editor of choice
MCP-native, hook-friendly, and CLI-first. q-ring slots into the agent toolchain you already use.
The honest comparison
Why q-ring instead of .env?
Other tools were built for a human at a keyboard. q-ring is built so AI coding agents can read, rotate, and audit keys without a plaintext file ever existing — and you can read every line of how.
| Capability | q-ring | .env files | dotenv-vault | 1Password CLI |
|---|---|---|---|---|
Anchored to OS keyringmacOS Keychain, Linux Secret Service, Windows Credential Vault | ||||
MCP-native (AI agents)Cursor / Claude / Kiro can read & rotate secrets | ||||
Auto-expiring keys (decay) | ||||
Per-environment isolation | ||||
Free + open source | AGPL-3.0 | — | ||
Audit log of agent reads | ||||
Zero cloud dependency | ||||
One-shot env injectionqring run -- node app.js | ||||
Pre/post-commit hooks |
Comparison reflects features at v0.12. PRs to update this table are welcome.
What ships in q-ring
Quantum Features
Twenty-three capabilities inspired by quantum physics — engineered for real-world secret management. Click any feature to peek at how it works.
Quick Start
Five commands. Your secrets are quantum-secured. Step through them.
# Store a secret (prompts securely if value is omitted) $ qring set OPENAI_API_KEY sk-...
Model Context Protocol
MCP Integration
44 tools for seamless AI agent integration. Pick a category to browse the tools, then drop the snippet into your editor.
| Tool | Description |
|---|---|
get_secret | Retrieve with superposition collapse + observer logging |
list_secrets | List keys with quantum metadata |
set_secret | Store with optional TTL, env state, tags |
delete_secret | Remove a secret |
has_secret | Boolean check (respects decay) |
export_secrets | Export as .env/JSON with key and tag filters |
import_dotenv | Parse and import secrets from .env content |
check_project | Validate secrets against .q-ring.json manifest |
env_generate | Generate .env from project manifest |
Configuration
Drop in your MCP config
Same single binary, every host. Pick your editor and paste.
{
"mcpServers": {
"q-ring": {
"command": "qring-mcp"
}
}
}Under the hood
Architecture
A modular core engine bridging CLI and MCP to your OS-native keyring. Hover or focus any module to see what it does.
core-engine/
Background daemon
Agent Mode
Autonomous background daemon that guards your secrets 24/7 — rotates, audits, and alerts so you don't have to.
Continuous Monitoring. Scans secret health at configurable intervals. Detects expiration, anomalies, and staleness in real time.
Auto-Rotation. Regenerates expired secrets via providers or quantum noise. Zero downtime, zero pages.
Anomaly Detection. Tracks access patterns and flags burst access, unusual hours, and suspicious behavior.
$ qring agent --interval 60 --auto-rotate --verbose
Drop into your editor
Editor Plugins
Quantum secret management built into Cursor, Kiro, and Claude Code. Rules, skills, agents, commands, hooks, and the MCP connector — pre-wired to q-ring's 44 tools. Click any card for details.
# One command per editor: $ qring setup cursor # or kiro / claude # Claude Code can also install from the marketplace: $ /plugin marketplace add I4cTime/q-ring
Operator surface
Status Dashboard
Headline KPIs, secrets table, manifest gaps, policy posture, approvals, hooks, anomalies, and a filterable 24h audit feed — streaming live from 127.0.0.1 with qring status.
All clear
No suspicious access in the last 7 days.
Live SSE updates
Snapshots stream every 5s. Search input, sort order, and scroll position survive each tick — no lost typing.
KPI strip + 14 panels
Headline KPIs, then health, env, manifest, policy, secrets table, decay, superposition, entanglement, tunnels, approvals, hooks, agent memory, anomalies, and a filterable audit feed.
Token-gated, local, never values
Self-contained Preact page on 127.0.0.1 — every route requires the per-launch ?token printed by qring status, other local users can't snoop, and secret values are never rendered, only metadata.
# Launch the dashboard (auto-opens your browser) $ qring status # Custom port $ qring status --port 4200 # Don't auto-open the browser $ qring status --no-open
One palette, every command.
Press ⌘K anywhere on this site to fuzzy-search every page, MCP tool, and CLI command. Hit Enter to copy, navigate, or open docs.
- 44 MCP tools grouped by capability — pick one to copy its tool name into your editor.
- 29 CLI examples across 9 groups — from
qring settoqring teleport pack. - Keyboard-first — arrow keys to navigate, Enter to act, Esc to close.
Common questions
Frequently asked
Everything you might want to know before adopting q-ring. If something isn't covered here, open an issue on GitHub — we update this list regularly.
Still curious? Open a question and we'll add it.
Free, open, and yours — forever.
q-ring is licensed under AGPL-3.0. Use it on personal projects, in your startup, inside your enterprise — no asterisks. The only commitment we ask back: improvements stay open so the next builder benefits too.
Every feature, every command, every MCP tool — no paywall, no premium tier, no upsell.
q-ring never phones home. The only outbound traffic is the provider call you explicitly request.
Your secrets live in your OS keyring. The dashboard runs on 127.0.0.1. There is no cloud.
Stop leaking secrets.
Start shipping with confidence.
Three minutes to install, zero seconds of cloud setup. q-ring meets your AI agents where they already live — and your secrets never have to.
Open source under AGPL-3.0. No accounts. No telemetry. No vendor lock-in. Read the code before you run it.