q-ring
The first quantum-inspired keyring built specifically for AI coding agents.
Stop pasting API keys into plain-text .env files or struggling with clunky secret managers. q-ring securely anchors your credentials to your OS's native vault (macOS Keychain, GNOME Keyring, Windows Credential Manager), then supercharges them with mechanics from quantum physics.
Experience superposition (multi-environment keys), entanglement (linked rotations), tunneling (in-memory ephemerality), and teleportation (encrypted sharing).
Seamlessly integrated with Cursor, Kiro, Claude Code, and the entire MCP ecosystem.
🚀 Installation
q-ring is designed to be installed globally so it's available anywhere in your terminal. Pick your favorite package manager:
# npm
npm install -g @i4ctime/q-ring
# pnpm (recommended)
pnpm add -g @i4ctime/q-ring
# yarn
yarn global add @i4ctime/q-ring
⚡ Quick Start
# 1️⃣ Store a secret (prompts securely if value is omitted)
qring set OPENAI_API_KEY sk-...
# 2️⃣ Retrieve it anytime
qring get OPENAI_API_KEY
# 3️⃣ List all keys (values are never shown)
qring list
# 4️⃣ Generate a cryptographic secret and save it
qring generate --format api-key --prefix "sk-" --save MY_KEY
# 5️⃣ Run a full health scan
qring health
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.
# Set environment-specific values
qring set API_KEY "sk-dev-123" --env dev
qring set API_KEY "sk-stg-456" --env staging
qring set API_KEY "sk-prod-789" --env prod
# Value resolves based on context
QRING_ENV=prod qring get API_KEY # → sk-prod-789
QRING_ENV=dev qring get API_KEY # → sk-dev-123
# Inspect the quantum state
qring inspect API_KEY
Wavefunction Collapse — Smart Environment Detection
q-ring auto-detects your environment without explicit flags. Resolution order:
--envflagQRING_ENVenvironment variableNODE_ENVenvironment variable- Git branch heuristics (
main/master→ prod,develop→ dev) .q-ring.jsonproject config- Default environment from the secret
# See what environment q-ring detects
qring env
# Project config (.q-ring.json)
echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json
Quantum Decay — Secrets with TTL
Secrets can have a time-to-live. Expired secrets are blocked from reads. Stale secrets (75%+ lifetime) trigger warnings.
# Set a secret that expires in 1 hour
qring set SESSION_TOKEN "tok-..." --ttl 3600
# Set with explicit expiry
qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"
# Health check shows decay status
qring health
Observer Effect — Audit Everything
Every secret read, write, and delete is logged. Access patterns are tracked for anomaly detection.
# View audit log
qring audit
qring audit --key OPENAI_KEY --limit 50
# Detect anomalies (burst access, unusual hours)
qring audit --anomalies
Quantum Noise — Secret Generation
Generate cryptographically strong secrets in common formats.
qring generate # API key (default)
qring generate --format password -l 32 # Strong password
qring generate --format uuid # UUID v4
qring generate --format token # Base64url token
qring generate --format hex -l 64 # 64-byte hex
qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY
Entanglement — Linked Secrets
Link secrets across projects. When you rotate one, all entangled copies update automatically.
# Entangle two secrets
qring entangle API_KEY API_KEY_BACKUP
# Now updating API_KEY also updates API_KEY_BACKUP
qring set API_KEY "new-value"
Tunneling — Ephemeral Secrets
Create secrets that exist only in memory. They never touch disk. Optional TTL and max-read self-destruction.
# Create an ephemeral secret (returns tunnel ID)
qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1
# Read it (self-destructs after this read)
qring tunnel read tun_abc123
# List active tunnels
qring tunnel list
Teleportation — Encrypted Sharing
Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines.
# Pack secrets (prompts for passphrase)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
# On another machine: unpack (prompts for passphrase)
cat bundle.txt | qring teleport unpack
# Preview without importing
qring teleport unpack <bundle> --dry-run
Agent Mode — Autonomous Monitoring
A background daemon that continuously monitors secret health, detects anomalies, and optionally auto-rotates expired secrets.
# Start the agent
qring agent --interval 60 --verbose
# With auto-rotation of expired secrets
qring agent --auto-rotate
# Single scan (for CI/cron)
qring agent --once
MCP Server
q-ring includes a full MCP server with 20 tools for AI agent integration.
Core Tools
| Tool | Description |
|---|---|
get_secret |
Retrieve with superposition collapse + observer logging |
list_secrets |
List keys with quantum metadata (never exposes values) |
set_secret |
Store with optional TTL, env state, tags |
delete_secret |
Remove a secret |
has_secret |
Boolean check (respects decay) |
Quantum Tools
| Tool | Description |
|---|---|
inspect_secret |
Full quantum state (states, decay, entanglement, access count) |
detect_environment |
Wavefunction collapse — detect current env context |
generate_secret |
Quantum noise — generate and optionally save secrets |
entangle_secrets |
Link two secrets for synchronized rotation |
Tunneling Tools
| Tool | Description |
|---|---|
tunnel_create |
Create ephemeral in-memory secret |
tunnel_read |
Read (may self-destruct) |
tunnel_list |
List active tunnels |
tunnel_destroy |
Immediately destroy |
Teleportation Tools
| Tool | Description |
|---|---|
teleport_pack |
Encrypt secrets into a portable bundle |
teleport_unpack |
Decrypt and import a bundle |
Observer & Health Tools
| Tool | Description |
|---|---|
audit_log |
Query access history |
detect_anomalies |
Scan for unusual access patterns |
health_check |
Full health report |
agent_scan |
Run autonomous agent scan |
Cursor / Kiro Configuration
Add to .cursor/mcp.json or .kiro/mcp.json:
If q-ring is installed globally (e.g. pnpm add -g @i4ctime/q-ring):
{
"mcpServers": {
"q-ring": {
"command": "qring-mcp"
}
}
}
If using a local clone:
{
"mcpServers": {
"q-ring": {
"command": "node",
"args": ["/path/to/quantum_ring/dist/mcp.js"]
}
}
}
Claude Code Configuration
Add to ~/.claude/claude_desktop_config.json:
Global install:
{
"mcpServers": {
"q-ring": {
"command": "qring-mcp"
}
}
}
Local clone:
{
"mcpServers": {
"q-ring": {
"command": "node",
"args": ["/path/to/quantum_ring/dist/mcp.js"]
}
}
}
Architecture
qring CLI ─────┐
├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
MCP Server ────┘ │
├── Envelope (quantum metadata)
├── Scope Resolver (global / project)
├── Collapse (env detection)
├── Observer (audit log)
├── Noise (secret generation)
├── Entanglement (cross-secret linking)
├── Tunnel (ephemeral in-memory)
├── Teleport (encrypted sharing)
└── Agent (autonomous monitor)
Project Config (.q-ring.json)
Optional per-project configuration:
{
"env": "dev",
"defaultEnv": "dev",
"branchMap": {
"main": "prod",
"develop": "dev",
"staging": "staging"
}
}
📜 License
Custom License - Free for personal and internal use. Distribution, sublicensing, or resale requires explicit permission.
