q-ring

The first quantum-inspired keyring
built for AI coding agents.

pnpm add -g @i4ctime/q-ring

scroll

MCP Tools

Quantum Features

Twenty-four capabilities inspired by quantum physics, engineered for real-world secret management.

Superposition

One key holds values for dev, staging, and prod simultaneously. The correct value resolves based on your current context.

qring set API_KEY "sk-dev" --env dev

Wavefunction Collapse

Auto-detects your environment from flags, env vars, git branches, and project config. Zero manual switching.

qring env

Quantum Decay

Secrets with TTL. Expired secrets are blocked, stale ones trigger warnings. Set explicit expiry or time-to-live.

qring set TOKEN "tok-..." --ttl 3600

Observer Effect

Every read, write, and delete is logged. Access patterns are tracked for anomaly detection and audit trails.

qring audit --anomalies

Quantum Noise

Generate cryptographically strong secrets in API key, password, UUID, token, or hex formats.

qring generate --format api-key

Entanglement

Link secrets across projects. When you rotate one, all entangled copies update automatically.

qring entangle API_KEY API_KEY_BACKUP

Tunneling

Ephemeral secrets that exist only in memory. Never touch disk. Optional TTL and max-read self-destruction.

qring tunnel create "temp-tok" --max-reads 1

Teleportation

Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines.

qring teleport pack --keys "API_KEY"

Liveness Validation

Test if a secret is actually valid with its target service. Auto-detects OpenAI, Stripe, GitHub, and AWS from key prefixes.

qring validate --all

Hooks

qring hook add --key DB_PASS --exec "..."

Project Manifest

Declare required secrets in .q-ring.json and validate project readiness with a single command.

qring check

Import

Migrate from .env files in one command. Supports standard dotenv syntax with comments, quotes, and escape sequences.

qring import .env --skip-existing

Env Sync

Generate .env files from the project manifest, resolving each key with environment-aware superposition collapse.

qring env:generate --output .env

Secure Execution

Run commands with secrets injected into the environment. All known values are auto-redacted from stdout and stderr.

qring exec -- npm run deploy

Codebase Scanner

Detect hardcoded credentials using regex heuristics and Shannon entropy analysis. Migrate legacy codebases fast.

qring scan .

Governance Policy

Define MCP tool gating, key access restrictions, exec allowlists, and secret lifecycle rules in .q-ring.json.

qring policy

User Approvals

Zero-trust MCP access. Sensitive secrets require HMAC-verified, scoped, time-limited approval tokens before reads.

qring approve PROD_DB_URL --for 3600

JIT Provisioning

Dynamically generate short-lived tokens on read. AWS STS role assumption, generic HTTP endpoints, and caching.

qring set AWS_KEYS '...' --jit-provider aws-sts

Agent Memory

Encrypted, persistent key-value store that survives across AI agent sessions. Remember decisions and context.

qring remember last_rotation "Rotated on 2026-03-21"

Secret Linter

Scan specific files for hardcoded secrets. Use --fix to auto-replace with process.env references and store in q-ring.

qring lint src/config.ts --fix

Team & Org Scopes

Share secrets across teams and orgs. Resolution cascades: project → team → org → global (most specific wins).

qring set SHARED_KEY "sk-..." --team my-team

Issuer-Native Rotation

Attempt provider-native secret rotation for supported services, or fall back to local quantum noise generation.

qring rotate STRIPE_KEY

Secret Analytics

Analyze usage patterns: most accessed secrets, unused/stale keys, scope optimization, and rotation recommendations.

qring analyze

Quick Start

Five commands. Your secrets are quantum-secured.

~ / terminal

# Store a secret (prompts securely if value is omitted)
$ qring set OPENAI_API_KEY sk-...

# Retrieve it anytime
$ qring get OPENAI_API_KEY

# List all keys (values are never shown)
$ qring list

# Generate a cryptographic secret and save it
$ qring generate--format api-key --prefix "sk-" --save MY_KEY

# Run a full health scan
$ qring health

MCP Integration

44 tools for seamless AI agent integration. Works with Cursor, Kiro, and Claude Code.

Core Tools

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

Quantum Tools

inspect_secret Full quantum state inspection
detect_environment Wavefunction collapse
generate_secret Quantum noise generation
entangle_secrets Link for synchronized rotation
disentangle_secrets Remove entanglement link

Tunneling Tools

tunnel_create Create ephemeral in-memory secret
tunnel_read Read (may self-destruct)
tunnel_list List active tunnels
tunnel_destroy Immediately destroy

Teleportation Tools

teleport_pack Encrypt into portable bundle
teleport_unpack Decrypt and import

Observer & Health

audit_log Query access history
detect_anomalies Scan for unusual patterns
verify_audit_chain Verify tamper-evident hash chain
export_audit Export audit events (jsonl/json/csv)
health_check Full health report
status_dashboard Launch live status dashboard
agent_scan Autonomous agent scan

Validation Tools

validate_secret Test if a secret is valid with its service
list_providers List available validation providers

Hook Tools

register_hook Register a callback on secret changes
list_hooks List registered hooks
remove_hook Remove a hook by ID

Execution & Scanning

exec_with_secrets Run commands with injected secrets and auto-redacted output
scan_codebase_for_secrets Scan directories for hardcoded secrets via entropy analysis
lint_files Lint files for hardcoded secrets with optional auto-fix

AI Agent Tools

get_project_context Safe, redacted overview for agent system prompts
agent_remember Store key-value in encrypted agent memory
agent_recall Retrieve from agent memory or list all keys
agent_forget Delete a key from agent memory
analyze_secrets Usage analytics and rotation recommendations

Governance & Policy

check_policy Check if an action is allowed by project policy
get_policy_summary Get governance policy configuration summary
rotate_secret Attempt issuer-native rotation via provider
ci_validate_secrets CI batch validation with structured pass/fail

Configuration

Cursor / Kiro

.cursor/mcp.json

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Claude Code

claude_desktop_config.json

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Architecture

A modular core engine bridging CLI and MCP to your OS-native keyring.

qring CLI

MCP Server

Core Engine

@napi-rs/keyring

OS Keyring

Agent Mode

Autonomous background daemon that guards your secrets 24/7.

Continuous Monitoring

Scans secret health at configurable intervals. Detects expiration, anomalies, and staleness.

Auto-Rotation

Automatically regenerates expired secrets using quantum noise. Zero downtime key rotation.

Anomaly Detection

Tracks access patterns and flags burst access, unusual hours, and suspicious behavior.

~ / agent

$ qring agent --interval 60 --auto-rotate --verbose

Status Dashboard

Real-time visibility into every quantum subsystem. One command, zero config.

127.0.0.1:9876

Health Summary

Environment

prod

Decay Timers

Entanglement

API_KEY ↔ API_BACKUPDB_PASS ↔ DB_REPLICA

Live SSE Updates

Data streams every 5 seconds via Server-Sent Events. No polling, no WebSocket complexity.

Eight Panels

Health, environment, decay timers, superposition, entanglement, tunnels, anomalies, and audit log.

Fully Local

Self-contained HTML served on localhost. No dependencies, no cloud, no data leaves your machine.

~ / terminal

# 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