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:

--env flag
QRING_ENV environment variable
NODE_ENV environment variable
Git branch heuristics (main/master → prod, develop → dev)
.q-ring.json project 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"

# Unlink entangled secrets
qring disentangle API_KEY API_KEY_BACKUP

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

Import — Bulk Secret Ingestion

Import secrets from .env files directly into q-ring. Supports standard dotenv syntax including comments, quoted values, and escape sequences.

# Import all secrets from a .env file
qring import .env

# Import to project scope, skipping existing keys
qring import .env --project --skip-existing

# Preview what would be imported
qring import .env --dry-run

Selective Export

Export only the secrets you need using key names or tag filters.

# Export specific keys
qring export --keys "API_KEY,DB_PASS,REDIS_URL"

# Export by tag
qring export --tags "backend"

# Combine with format
qring export --keys "API_KEY,DB_PASS" --format json

Secret Search and Filtering

Filter qring list output by tag, expiry state, or key pattern.

# Filter by tag
qring list --tag backend

# Show only expired secrets
qring list --expired

# Show only stale secrets (75%+ decay)
qring list --stale

# Glob pattern on key name
qring list --filter "API_*"

Project Secret Manifest

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

# Validate project secrets against the manifest
qring check

# See which secrets are present, missing, expired, or stale
qring check --project-path /path/to/project

Env File Sync

Generate a .env file from the project manifest, resolving each key from q-ring with environment-aware superposition collapse.

# Generate to stdout
qring env:generate

# Write to a file
qring env:generate --output .env

# Force a specific environment
qring env:generate --env staging --output .env.staging

Secret Liveness Validation

Test if a secret is actually valid with its target service. q-ring auto-detects the provider from key prefixes (sk- → OpenAI, ghp_ → GitHub, etc.) or accepts an explicit provider name.

# Validate a single secret
qring validate OPENAI_API_KEY

# Force a specific provider
qring validate SOME_KEY --provider stripe

# Validate all secrets with detectable providers
qring validate --all

# Only validate manifest-declared secrets
qring validate --all --manifest

# List available providers
qring validate --list-providers

Built-in providers: OpenAI, Stripe, GitHub, AWS (format check), Generic HTTP.

Output:

  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
  ○ DATABASE_URL     unknown  — no provider detected

Hooks — Callbacks on Secret Change

Register webhooks, shell commands, or process signals that fire when secrets are created, updated, or deleted. Supports key matching, glob patterns, tag filtering, and scope constraints.

# Run a shell command when a secret changes
qring hook add --key DB_PASS --exec "docker restart app"

# POST to a webhook on any write/delete
qring hook add --key API_KEY --url "https://hooks.example.com/rotate"

# Trigger on all secrets tagged "backend"
qring hook add --tag backend --exec "pm2 restart all"

# Signal a process when DB secrets change
qring hook add --key-pattern "DB_*" --signal-target "node"

# List all hooks
qring hook list

# Remove a hook
qring hook remove <id>

# Enable/disable
qring hook enable <id>
qring hook disable <id>

# Dry-run test a hook
qring hook test <id>

Hooks are fire-and-forget: a failing hook never blocks secret operations. The hook registry is stored at ~/.config/q-ring/hooks.json.

Configurable Rotation

Set a rotation format per secret so the agent auto-rotates with the correct value shape.

# Store a secret with rotation format metadata
qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"

# Store a password with password rotation format
qring set DB_PASS "..." --rotation-format password

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

Quantum Status Dashboard — Live Monitoring

Launch a real-time dashboard in your browser that visualizes every quantum subsystem at a glance: health summary, decay timers, superposition states, entanglement pairs, active tunnels, anomaly alerts, audit log, and environment detection.

The dashboard is a self-contained HTML page served locally. Data streams in via Server-Sent Events and updates every 5 seconds — no dependencies, no cloud, no config.

# Open the dashboard (auto-launches your browser)
qring status

# Specify a custom port
qring status --port 4200

# Don't auto-open the browser
qring status --no-open

MCP Server

q-ring includes a full MCP server with 31 tools for AI agent integration.

Core Tools

Tool	Description
`get_secret`	Retrieve with superposition collapse + observer logging
`list_secrets`	List keys with quantum metadata, filterable by tag/expiry/pattern
`set_secret`	Store with optional TTL, env state, tags, rotation format
`delete_secret`	Remove a secret
`has_secret`	Boolean check (respects decay)
`export_secrets`	Export as .env/JSON with optional key and tag filters
`import_dotenv`	Parse and import secrets from .env content
`check_project`	Validate project secrets against `.q-ring.json` manifest
`env_generate`	Generate .env content from the project manifest

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
`disentangle_secrets`	Remove entanglement between two secrets

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

Validation Tools

Tool	Description
`validate_secret`	Test if a secret is valid with its target service (OpenAI, Stripe, GitHub, etc.)
`list_providers`	List all available validation providers

Hook Tools

Tool	Description
`register_hook`	Register a shell/HTTP/signal callback on secret changes
`list_hooks`	List all registered hooks with match criteria and status
`remove_hook`	Remove a registered hook by ID

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 + branchMap globs)
                       ├── Observer (audit log)
                       ├── Noise (secret generation)
                       ├── Entanglement (cross-secret linking)
                       ├── Validate (provider-based liveness checks)
                       ├── Hooks (shell/HTTP/signal callbacks)
                       ├── Import (.env file ingestion)
                       ├── Tunnel (ephemeral in-memory)
                       ├── Teleport (encrypted sharing)
                       ├── Agent (autonomous monitor + rotation)
                       └── Dashboard (live status via SSE)

Project Config (`.q-ring.json`)

Optional per-project configuration:

{
  "env": "dev",
  "defaultEnv": "dev",
  "branchMap": {
    "main": "prod",
    "develop": "dev",
    "staging": "staging",
    "release/*": "staging",
    "feature/*": "dev"
  },
  "secrets": {
    "OPENAI_API_KEY": { "required": true, "description": "OpenAI API key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
  }
}

branchMap supports glob patterns with * wildcards (e.g., release/* matches release/v1.0)
secrets declares the project's required secrets — use qring check to validate, qring env:generate to produce a .env file
provider associates a liveness validation provider with a secret (e.g., "openai", "stripe", "github") — use qring validate to test
validationUrl configures the generic HTTP provider's endpoint for custom validation

📜 License

AGPL-3.0 - Free to use, modify, and share. Any derivative work or hosted service must release its source code under the same license.

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github		.github
assets		assets
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
glama.json		glama.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
server.json		server.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

q-ring

🚀 Installation

⚡ Quick Start

Quantum Features

Superposition — One Key, Multiple Environments

Wavefunction Collapse — Smart Environment Detection

Quantum Decay — Secrets with TTL

Observer Effect — Audit Everything

Quantum Noise — Secret Generation

Entanglement — Linked Secrets

Tunneling — Ephemeral Secrets

Teleportation — Encrypted Sharing

Import — Bulk Secret Ingestion

Selective Export

Secret Search and Filtering

Project Secret Manifest

Env File Sync

Secret Liveness Validation

Hooks — Callbacks on Secret Change

Configurable Rotation

Agent Mode — Autonomous Monitoring

Quantum Status Dashboard — Live Monitoring

MCP Server

Core Tools

Quantum Tools

Tunneling Tools

Teleportation Tools

Validation Tools

Hook Tools

Observer & Health Tools

Cursor / Kiro Configuration

Claude Code Configuration

Architecture

Project Config (.q-ring.json)

📜 License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Project Config (`.q-ring.json`)

Packages