I4cTime/quantum_ring

**OS keychain secrets for AI coding agents, over MCP.**
Stop pasting API keys into plain-text .env files or wrestling with clunky secret managers. **q-ring** securely anchors your credentials to your OS's native vault (macOS Keychain, Linux Secret Service, Windows Credential Vault) and supercharges them with mechanics from quantum physics.
> 📖 **View the Official Documentation** for a complete CLI reference, MCP prompt cookbooks, and architecture details.
Why q-ring?
- **Superposition:** Store one key with multiple states (dev/staging/prod) that collapse based on context.
- **Entanglement:** Link keys across projects so rotating one automatically updates them all.
- **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.
- **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.
- **Seamless AI Integration:** 46 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.
🚀 Installation
q-ring is designed to be installed globally so it's available anywhere in your terminal. Pick your favorite package manager:
Docker (MCP server)
The repo ships a Dockerfile that builds the MCP server and exposes it through mcp-proxy — useful for hosted MCP deployments (e.g. Glama) or keeping the server off the host entirely:
> Note: inside a container there is no OS keychain (GNOME Keyring / macOS Keychain), so this path is for the MCP protocol surface, ephemeral use, and CI experiments — not for durable local secret storage. For day-to-day use install the CLI natively via one of the package managers above.
⚡ Quick Start
Quantum Features
Superposition — One Key, Multiple Environments
A single secret can hold different values for dev, staging, and prod simultaneously. The correct value resolves based on your current context.
Environment Promotion — Diff, Then Promote
Once a secret carries per-environment states, promotion replaces copy-paste: compare two environments key by key (statuses only, never values), then copy a value from one state to another. diff exits 1 on drift, so it doubles as a CI gate; promote refuses to overwrite a differing target unless you say so.
MCP agents get the same two operations as diff_environments and promote_secret.
Wavefunction Collapse — Smart Environment Detection
q-ring auto-detects your environment without explicit flags. Resolution order:
1. --env flag
2. QRING_ENV environment variable
3. NODE_ENV environment variable
4. Git branch heuristics (main/master → prod, develop → dev)
5. .q-ring.json project config
6. Default environment from the secret
Quantum Decay — Secrets with TTL
Secrets can have a time-to-live. Expired secrets are blocked from reads. Stale secrets (75%+ lifetime) trigger warnings.
Observer Effect — Audit Everything
Every secret read, write, and delete is logged with a tamper-evident hash chain. Access patterns are tracked for anomaly detection.
Quantum Noise — Secret Generation
Generate cryptographically strong secrets in common formats.
Entanglement — Linked Secrets
Link secrets across projects. When you rotate one, all entangled copies update automatically.
Tunneling — Ephemeral Secrets
Create secrets that exist only in memory. They never touch disk. Optional TTL and max-read self-destruction.
Teleportation — Encrypted Sharing
Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines. Two ways to lock a bundle:
- **Passphrase** (v1): keys derived with PBKDF2-HMAC-SHA512 (210 000 iterations); each bundle records its iteration count, so old bundles still unpack.
- **Recipients** (v2, 0.18): each teammate runs qring teleport keygen once and shares their recipient string (qring1…, an X25519 public key; the private half lives in their OS keyring). pack --to encrypts a fresh content key to every recipient — HKDF-SHA256 over an ephemeral X25519 agreement, AES-256-GCM throughout, node:crypto only — so nothing secret travels beside the bundle and nobody has to whisper a passphrase.
Import — Bulk Secret Ingestion
Import secrets from .env files directly into q-ring. Supports standard dotenv syntax including comments, quoted values, and escape sequences. The CLI accepts either a file path or raw content; the import_dotenv MCP tool only accepts raw content (it never reads files from disk) so an agent can't coerce it into reading arbitrary local files.
Selective Export
Export only the secrets you need using key names or tag filters.
Secret Search and Filtering