q-ring — Quantum Keyring for AI Agents

Quantum Features

Thirteen mechanics 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

Register shell commands, HTTP webhooks, or process signals that fire when secrets are written, deleted, or rotated.

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

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

31 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
health_check Full health report
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

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

Envelope Scope Collapse Observer Noise Entanglement Validate Hooks Import Tunnel Teleport Agent Dashboard

▶

@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

12

Environment

prod

Decay Timers

Entanglement

API_KEY ↔ API_BACKUP DB_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