q-ring

q-ring

OS keychain secrets for AI coding agents, over MCP.

Website: qring.i4c.studio

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](https://qring.i4c.studio/docs) 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:

# pnpm (recommended)

pnpm add -g @i4ctime/q-ring

npm

npm install -g @i4ctime/q-ring

yarn

yarn global add @i4ctime/q-ring

Homebrew (macOS / Linux)

brew install i4ctime/tap/qring

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:

git clone https://github.com/I4cTime/q-ring.git

cd q-ring docker build -t qring-mcp . docker run --rm -p 8080:8080 qring-mcp

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

# 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

Something not working? Diagnose the install (keyring, audit, MCP wiring)

qring doctor

Tab completion for your shell

qring completion zsh > ~/.zsh/completions/_qring # also: bash, fish

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

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.

# What differs between staging and prod? (same / different / missing on one side)

qring diff staging prod

Make prod match staging for one key (asks before overwriting a different value)

qring promote DATABASE_URL --from staging --to prod

Non-interactive, e.g. in a release script

qring promote DATABASE_URL --from staging --to prod --force --json

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

# 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 with a tamper-evident hash chain. 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, chain tampering)

qring audit --anomalies

Verify audit chain integrity

qring audit:verify

Export audit log

qring audit:export --format json --since 2026-03-01 qring audit:export --format csv --output audit-report.csv

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. 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.

# Passphrase bundle (prompts)

qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt cat bundle.txt | qring teleport unpack

Recipient bundle: teammates publish their recipient once…

qring teleport keygen # → qring1a3F… (share this; keep the keyring) qring teleport identity # print it again later

…then you address the pack to them (repeatable or comma-separated)

qring teleport pack --keys "API_KEY,DB_PASS" --to qring1a3F… --to qring1Zz9… > bundle.txt

They unpack with the identity in their keyring — no passphrase

cat bundle.txt | qring teleport unpack

Preview: who it's addressed to, whether that's you, and what's inside

qring teleport unpack --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. 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.

# 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_*"

Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)

qring has OPENAI_API_KEY --quiet && echo "configured"

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