\n\n# q-ring\n\n**OS keychain secrets for AI coding agents, over MCP.**\n\n[](https://github.com/I4cTime/q-ring/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/@i4ctime/q-ring)\n[](https://www.npmjs.com/package/@i4ctime/q-ring)\n[](https://qring.i4c.studio/docs)\n[](https://glama.ai/mcp/servers/I4cTime/q-ring)\n[](https://smithery.ai/servers/i4ctime/q-ring)\n[](https://cursor.directory/plugins/q-ring)\n[](https://www.pulsemcp.com/servers/i4ctime-q-ring)\n[](https://mcpservers.org/servers/i4ctime/q-ring)\n[](https://github.com/I4cTime/q-ring/blob/main/LICENSE)\n[](https://discord.gg/5uEApw5uEz)\n[](https://www.youtube.com/@qring_dev)\n[](https://x.com/i4c_studio)\n\n\n \n\n\nStop 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.\n\n> ๐ **[View the Official Documentation](https://qring.i4c.studio/docs)** for a complete CLI reference, MCP prompt cookbooks, and architecture details.\n\n### Why q-ring?\n- **Superposition:** Store one key with multiple states (dev/staging/prod) that collapse based on context.\n- **Entanglement:** Link keys across projects so rotating one automatically updates them all.\n- **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.\n- **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.\n- **Seamless AI Integration:** 44 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.\n\n## ๐ Installation\n\nq-ring is designed to be installed globally so it's available anywhere in your terminal. Pick your favorite package manager:\n\n```bash\n# pnpm (recommended)\npnpm add -g @i4ctime/q-ring\n\n# npm\nnpm install -g @i4ctime/q-ring\n\n# yarn\nyarn global add @i4ctime/q-ring\n\n# Homebrew (macOS / Linux)\nbrew install i4ctime/tap/qring\n```\n\n### Docker (MCP server)\n\nThe repo ships a `Dockerfile` that builds the MCP server and exposes it through [`mcp-proxy`](https://github.com/punkpeye/mcp-proxy) โ useful for hosted MCP deployments (e.g. Glama) or keeping the server off the host entirely:\n\n```bash\ngit clone https://github.com/I4cTime/q-ring.git\ncd q-ring\ndocker build -t qring-mcp .\ndocker run --rm -p 8080:8080 qring-mcp\n```\n\n> 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.\n\n## โก Quick Start\n\n```bash\n# 1๏ธโฃ Store a secret (prompts securely if value is omitted)\nqring set OPENAI_API_KEY sk-...\n\n# 2๏ธโฃ Retrieve it anytime\nqring get OPENAI_API_KEY\n\n# 3๏ธโฃ List all keys (values are never shown)\nqring list\n\n# 4๏ธโฃ Generate a cryptographic secret and save it\nqring generate --format api-key --prefix \"sk-\" --save MY_KEY\n\n# 5๏ธโฃ Run a full health scan\nqring health\n\n# Something not working? Diagnose the install (keyring, audit, MCP wiring)\nqring doctor\n\n# Tab completion for your shell\nqring completion zsh > ~/.zsh/completions/_qring # also: bash, fish\n```\n\n## Quantum Features\n\n### Superposition โ One Key, Multiple Environments\n\nA single secret can hold different values for dev, staging, and prod simultaneously. The correct value resolves based on your current context.\n\n```bash\n# Set environment-specific values\nqring set API_KEY \"sk-dev-123\" --env dev\nqring set API_KEY \"sk-stg-456\" --env staging\nqring set API_KEY \"sk-prod-789\" --env prod\n\n# Value resolves based on context\nQRING_ENV=prod qring get API_KEY # โ sk-prod-789\nQRING_ENV=dev qring get API_KEY # โ sk-dev-123\n\n# Inspect the quantum state\nqring inspect API_KEY\n```\n\n### Wavefunction Collapse โ Smart Environment Detection\n\nq-ring auto-detects your environment without explicit flags. Resolution order:\n\n1. `--env` flag\n2. `QRING_ENV` environment variable\n3. `NODE_ENV` environment variable\n4. Git branch heuristics (`main`/`master` โ prod, `develop` โ dev)\n5. `.q-ring.json` project config\n6. Default environment from the secret\n\n```bash\n# See what environment q-ring detects\nqring env\n\n# Project config (.q-ring.json)\necho '{\"env\": \"staging\", \"branchMap\": {\"release/*\": \"staging\"}}' > .q-ring.json\n```\n\n### Quantum Decay โ Secrets with TTL\n\nSecrets can have a time-to-live. Expired secrets are blocked from reads. Stale secrets (75%+ lifetime) trigger warnings.\n\n```bash\n# Set a secret that expires in 1 hour\nqring set SESSION_TOKEN \"tok-...\" --ttl 3600\n\n# Set with explicit expiry\nqring set CERT_KEY \"...\" --expires \"2026-06-01T00:00:00Z\"\n\n# Health check shows decay status\nqring health\n```\n\n### Observer Effect โ Audit Everything\n\nEvery secret read, write, and delete is logged with a tamper-evident hash chain. Access patterns are tracked for anomaly detection.\n\n```bash\n# View audit log\nqring audit\nqring audit --key OPENAI_KEY --limit 50\n\n# Detect anomalies (burst access, unusual hours, chain tampering)\nqring audit --anomalies\n\n# Verify audit chain integrity\nqring audit:verify\n\n# Export audit log\nqring audit:export --format json --since 2026-03-01\nqring audit:export --format csv --output audit-report.csv\n```\n\n### Quantum Noise โ Secret Generation\n\nGenerate cryptographically strong secrets in common formats.\n\n```bash\nqring generate # API key (default)\nqring generate --format password -l 32 # Strong password\nqring generate --format uuid # UUID v4\nqring generate --format token # Base64url token\nqring generate --format hex -l 64 # 64-byte hex\nqring generate --format api-key --prefix \"sk-live-\" --save STRIPE_KEY\n```\n\n### Entanglement โ Linked Secrets\n\nLink secrets across projects. When you rotate one, all entangled copies update automatically.\n\n```bash\n# Entangle two secrets\nqring entangle API_KEY API_KEY_BACKUP\n\n# Now updating API_KEY also updates API_KEY_BACKUP\nqring set API_KEY \"new-value\"\n\n# Unlink entangled secrets\nqring disentangle API_KEY API_KEY_BACKUP\n```\n\n### Tunneling โ Ephemeral Secrets\n\nCreate secrets that exist only in memory. They never touch disk. Optional TTL and max-read self-destruction.\n\n```bash\n# Create an ephemeral secret (returns tunnel ID)\nqring tunnel create \"temporary-token-xyz\" --ttl 300 --max-reads 1\n\n# Read it (self-destructs after this read)\nqring tunnel read tun_abc123\n\n# List active tunnels\nqring tunnel list\n```\n\n### Teleportation โ Encrypted Sharing\n\nPack secrets into AES-256-GCM encrypted bundles for secure transfer between machines. Keys are derived with PBKDF2-HMAC-SHA512 (210 000 iterations) from your passphrase; each bundle records its iteration count, so bundles produced by older versions still unpack.\n\n```bash\n# Pack secrets (prompts for passphrase)\nqring teleport pack --keys \"API_KEY,DB_PASS\" > bundle.txt\n\n# On another machine: unpack (prompts for passphrase)\ncat bundle.txt | qring teleport unpack\n\n# Preview without importing\nqring teleport unpack --dry-run\n```\n\n### Import โ Bulk Secret Ingestion\n\nImport 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.\n\n```bash\n# Import all secrets from a .env file\nqring import .env\n\n# Import to project scope, skipping existing keys\nqring import .env --project --skip-existing\n\n# Preview what would be imported\nqring import .env --dry-run\n```\n\n### Selective Export\n\nExport only the secrets you need using key names or tag filters.\n\n```bash\n# Export specific keys\nqring export --keys \"API_KEY,DB_PASS,REDIS_URL\"\n\n# Export by tag\nqring export --tags \"backend\"\n\n# Combine with format\nqring export --keys \"API_KEY,DB_PASS\" --format json\n```\n\n### Secret Search and Filtering\n\nFilter `qring list` output by tag, expiry state, or key pattern.\n\n```bash\n# Filter by tag\nqring list --tag backend\n\n# Show only expired secrets\nqring list --expired\n\n# Show only stale secrets (75%+ decay)\nqring list --stale\n\n# Glob pattern on key name\nqring list --filter \"API_*\"\n\n# Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)\nqring has OPENAI_API_KEY --quiet && echo \"configured\"\n```\n\n### Project Secret Manifest\n\nDeclare required secrets in `.q-ring.json` and validate project readiness with a single command.\n\n```bash\n# Validate project secrets against the manifest\nqring check\n\n# See which secrets are present, missing, expired, or stale\nqring check --project-path /path/to/project\n```\n\n### Env File Sync\n\nGenerate a `.env` file from the project manifest, resolving each key from q-ring with environment-aware superposition collapse.\n\n```bash\n# Generate to stdout\nqring env:generate\n\n# Write to a file\nqring env:generate --output .env\n\n# Force a specific environment\nqring env:generate --env staging --output .env.staging\n```\n\n### Secret References & Least-Privilege Run\n\nA `qring://` reference is a committable pointer to a secret โ it goes in your `.env` file instead of the value. `qring run` resolves references and manifest keys at spawn time, injecting **only what the project declares** (unlike `exec`, which injects the whole scope). Output is auto-redacted.\n\n```bash\n# .env โ safe to commit: these are references, not values\nDATABASE_URL=qring://project/DATABASE_URL\nOPENAI_API_KEY=qring://global/OPENAI_API_KEY\nSTRIPE_KEY=qring:///STRIPE_KEY # auto scope: project, then global\nSESSION_TTL=3600 # plain values pass through\n\n# Run with declared secrets injected (manifest + .env refs)\nqring run -- pnpm dev\n\n# Preview what would be injected, without running\nqring run --dry-run -- pnpm dev\n\n# Pin an environment, use a specific env file, or skip the manifest\nqring run --env prod --env-file .env.prod --no-manifest -- ./deploy.sh\n```\n\nThe key lives in the **path**, never the host (`qring://project/KEY`, not `qring://KEY`) โ URL hosts are case-insensitive, and env-var keys are not. Malformed references fail loudly instead of leaking a literal `qring://โฆ` string into the child. A reference pinned to an environment: `qring://project/DATABASE_URL?env=prod`.\n\n### Editor Setup\n\nWire the q-ring MCP server into an editor's MCP config with one command. Merges non-destructively โ other servers are preserved, and an existing q-ring entry is only replaced with `--force`.\n\n```bash\nqring setup cursor # .cursor/mcp.json (project) or --global for ~/.cursor\nqring setup kiro # .kiro/settings/mcp.json, with read-only autoApprove list\nqring setup claude # .mcp.json (project scope)\n\n# Preview without writing\nqring setup cursor --dry-run\n```\n\n### Push to Deployment Platforms\n\nPush manifest secrets to GitHub Actions, Vercel, or Cloudflare Workers through each platform's **own authenticated CLI** (`gh` / `vercel` / `wrangler`) โ q-ring never holds platform tokens, and values travel over stdin, never argv. Every push is recorded in the audit chain.\n\n```bash\n# Push the .q-ring.json manifest keys to GitHub Actions secrets\nqring push github --repo you/your-app\n\n# Push to Vercel environments\nqring push vercel --vercel-env production,preview\n\n# Push to Cloudflare Workers secrets\nqring push cloudflare\n\n# Explicit keys, preview first\nqring push github --keys DATABASE_URL,API_KEY --dry-run\n```\n\n### Secret Liveness Validation\n\nTest 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.\n\n```bash\n# Validate a single secret\nqring validate OPENAI_API_KEY\n\n# Force a specific provider\nqring validate SOME_KEY --provider stripe\n\n# Validate all secrets with detectable providers\nqring validate --all\n\n# Only validate manifest-declared secrets\nqring validate --all --manifest\n\n# List available providers\nqring validate --list-providers\n```\n\n**Built-in providers:** OpenAI, Anthropic, OpenRouter, Google AI (Gemini), Groq, Hugging Face, ElevenLabs*, Vercel*, Stripe, GitHub, AWS (format check), Generic HTTP. Keys are only ever sent in headers, never URLs. (*no safe public prefix โ select explicitly with `--provider` or the manifest `provider` field.)\n\nOutput:\n\n```\n โ OPENAI_API_KEY valid (openai, 342ms)\n โ STRIPE_KEY invalid (stripe, 128ms) โ API key has been revoked\n โ AWS_ACCESS_KEY error (aws, 10002ms) โ network timeout\n โ DATABASE_URL unknown โ no provider detected\n```\n\n### Hooks โ Callbacks on Secret Change\n\nRegister 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.\n\n```bash\n# Run a shell command when a secret changes\nqring hook add --key DB_PASS --exec \"docker restart app\"\n\n# POST to a webhook on any write/delete\nqring hook add --key API_KEY --url \"https://hooks.example.com/rotate\"\n\n# Trigger on all secrets tagged \"backend\"\nqring hook add --tag backend --exec \"pm2 restart all\"\n\n# Signal a process when DB secrets change\nqring hook add --key-pattern \"DB_*\" --signal-target \"node\"\n\n# List all hooks\nqring hook list\n\n# Remove a hook\nqring hook remove \n\n# Enable/disable\nqring hook enable \nqring hook disable \n\n# Dry-run test a hook\nqring hook test \n```\n\nHooks are fire-and-forget: a failing hook never blocks secret operations. The hook registry is stored at `~/.config/q-ring/hooks.json`.\n\n**SSRF protection:** HTTP hook URLs targeting private/loopback IP ranges (`127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `::1`, `fc00::/7`) are blocked by default. DNS is checked up front *and* re-validated at connect time, so a hostname can't pass the check then rebind to a private address before the socket opens. To allow hooks targeting local services (e.g. during development), set the environment variable `Q_RING_ALLOW_PRIVATE_HOOKS=1`.\n\n### Configurable Rotation\n\nSet a rotation format per secret so the agent auto-rotates with the correct value shape.\n\n```bash\n# Store a secret with rotation format metadata\nqring set STRIPE_KEY \"sk-...\" --rotation-format api-key --rotation-prefix \"sk-\"\n\n# Store a password with password rotation format\nqring set DB_PASS \"...\" --rotation-format password\n```\n\n### Secure Execution & Auto-Redaction\n\nRun commands with secrets securely injected into the environment. All known secret values are automatically redacted from stdout and stderr to prevent leaking into terminal logs or agent transcripts. Exec profiles restrict which commands may be run.\n\n```bash\n# Execute a deployment script with secrets injected\nqring exec -- npm run deploy\n\n# Inject only specific tags\nqring exec --tags backend -- node server.js\n\n# Run with a restricted profile (blocks network tools and interpreters/shells, 30s timeout)\nqring exec --profile restricted -- npm test\n```\n\n### Codebase Secret Scanner\n\nMigrating a legacy codebase? Quickly scan directories for hardcoded credentials using regex heuristics and Shannon entropy analysis.\n\n```bash\n# Scan current directory\nqring scan .\n```\n\nOutput:\n```\n โ src/db/connection.js:12\n Key: DB_PASSWORD\n Entropy: 4.23\n Context: const DB_PASSWORD = \"...\"\n```\n\n### Composite / Templated Secrets\n\nStore complex connection strings that dynamically resolve other secrets. If `DB_PASS` rotates, `DB_URL` is automatically correct without manual updates.\n\n```bash\nqring set DB_USER \"admin\"\nqring set DB_PASS \"supersecret\"\nqring set DB_URL \"postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb\"\n\n# Resolves embedded templates automatically\nqring get DB_URL \n# Output: postgres://admin:supersecret@localhost/mydb\n```\n\n### User Approvals (Zero-Trust Agent)\n\nProtect sensitive production secrets from being read autonomously by the MCP server without explicit user approval. Each approval token is HMAC-verified, scoped, reasoned, and time-limited. The gate applies to bulk reads too โ `export_secrets` and `teleport_pack` over MCP skip approval-protected keys that lack a valid grant.\n\n```bash\n# Mark a secret as requiring approval\nqring set PROD_DB_URL \"...\" --requires-approval\n\n# Temporarily grant MCP access for 1 hour with a reason\nqring approve PROD_DB_URL --for 3600 --reason \"deploying v2.0\"\n\n# List all approvals with verification status\nqring approvals\n\n# Revoke an approval\nqring approve PROD_DB_URL --revoke\n```\n\nWhen an agent is blocked on an approval-protected key, q-ring raises a desktop notification (Linux `notify-send`, macOS `osascript`) naming the key and the exact `qring approve` command โ throttled per key, disabled with `QRING_NOTIFY=off`.\n\n### Canary Honeytokens\n\nPlant fake credentials that look and read exactly like real ones. Anything that touches one โ a compromised MCP server, an over-curious agent, exfiltrated tooling sweeping the ring โ gets the fake value back with no tell, while q-ring fires a desktop alert and writes a `canary` event into the tamper-evident audit chain.\n\n```bash\n# Plant a canary shaped like a real AWS access key\nqring canary plant AWS_SECRET_ACCESS_KEY --format aws\n\n# Other shapes: github, openai, anthropic, stripe, generic\nqring canary plant GHP_BACKUP_TOKEN --format github\n\n# See what's been tripped\nqring canary list\nqring audit --action canary\n```\n\nValues are CSPRNG noise in the provider's real token shape (an `aws` canary matches `AKIA[A-Z0-9]{16}`) โ plausible enough to be taken, never valid. Alerts are throttled to one per key per 30 seconds; the audit trail records every read.\n\nCanaries are built to stay covert: they carry no identifying description (add an innocuous cover story with `--description` if you like), their flag never appears in MCP tool responses, and trip records are visible only from the operator's terminal โ never to agents via MCP audit tools. Bulk `export` and `delete` trip them just like reads, so sweeping the ring or removing the tripwire both ring the bell. Done with one? `qring canary disarm ` turns it back into an ordinary secret (`qring set` over a canary warns you first โ the flag deliberately survives overwrites so an agent can't launder it away).\n\n### MCP Airlock\n\nRun a third-party MCP server behind q-ring. The airlock sits between your agent host and the wrapped server, spawns it with a **stripped environment** (no inherited API keys โ opt back in with `--inherit-env`), and records every tool call that crosses it as a `wrap` event in the audit chain, grouped per session and labeled with the calling client's identity. Tool arguments are never logged โ they may contain secrets.\n\n```json\n{\n \"mcpServers\": {\n \"some-server\": {\n \"command\": \"qring\",\n \"args\": [\"mcp\", \"wrap\", \"--\", \"npx\", \"-y\", \"some-mcp-server\"]\n }\n }\n}\n```\n\nTools-only proxy today: `tools/list` and `tools/call` pass through verbatim (pagination, progress notifications, cancellation, and `tools/list_changed` included; long-running tools are governed by the host's own timeout, with a generous airlock ceiling configurable via `QRING_WRAP_TIMEOUT_MS`). A wrapped server's *resources and prompts* are not proxied yet โ a resources-heavy server will look tools-only behind the airlock.\n\nBe clear about what the airlock is: env stripping plus a tamper-evident record of every tool call. It is **not a sandbox** โ the wrapped process still runs as your user with normal filesystem, network, and OS-keychain access, and tool descriptions/results pass through uninspected. See `docs/threat-model.md` for the honest boundary picture.\n\n### Just-In-Time (JIT) Provisioning\n\nInstead of storing static credentials, configure `q-ring` to dynamically generate short-lived tokens on the fly when requested (e.g. AWS STS, generic HTTP endpoints).\n\n```bash\n# Store the STS role configuration\nqring set AWS_TEMP_KEYS '{\"roleArn\":\"arn:aws:iam::123:role/AgentRole\", \"durationSeconds\":3600}' --jit-provider aws-sts\n\n# Resolving the secret automatically assumes the role and caches the temporary token\nqring get AWS_TEMP_KEYS\n```\n\n### Project Context for AI Agents\n\nA safe, redacted overview of the project's secrets, configuration, and state. Designed to be fed into an AI agent's system prompt without ever exposing secret values.\n\n```bash\n# Human-readable summary\nqring context\n\n# JSON output (for MCP / programmatic use)\nqring context --json\n```\n\n### Secret-Aware Linter\n\nScan specific files for hardcoded secrets with optional auto-fix. When `--fix` is used, detected secrets are replaced with `process.env.KEY` references and stored in q-ring.\n\n```bash\n# Lint files for hardcoded secrets\nqring lint src/config.ts src/db.ts\n\n# Auto-fix: replace hardcoded values and store in q-ring\nqring lint src/config.ts --fix\n\n# Scan entire directory with auto-fix\nqring scan . --fix\n```\n\n### Agent Memory\n\nEncrypted, persistent key-value store that survives across AI agent sessions. Useful for remembering rotation history, project decisions, or context.\n\n```bash\n# Store a memory\nqring remember last_rotation \"Rotated STRIPE_KEY on 2026-03-21\"\n\n# Retrieve it\nqring recall last_rotation\n\n# List all memories\nqring recall\n\n# Forget\nqring forget last_rotation\n```\n\n### Pre-Commit Secret Scanning\n\nInstall a git pre-commit hook that automatically blocks commits containing hardcoded secrets.\n\n```bash\n# Install the hook\nqring hook:install\n\n# Uninstall\nqring hook:uninstall\n```\n\n### Secret Analytics\n\nAnalyze usage patterns and get optimization suggestions for your secrets.\n\n```bash\nqring analyze\n```\n\nOutput includes most accessed secrets, unused/stale secrets, scope optimization suggestions, and rotation recommendations.\n\n### Service Setup Wizard\n\nQuickly set up a new service integration with secrets, manifest entries, and hooks in one command.\n\n```bash\n# Create secrets for a new Stripe integration\nqring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment\n\n# With a hook to restart the app on change\nqring wizard myservice --hook-exec \"pm2 restart app\"\n```\n\n### Governance Policy\n\nDefine project-level governance rules in `.q-ring.json` to control which MCP tools can be used, which keys are accessible, and which commands can be executed. Policy is enforced at both the MCP server and keyring level.\n\nOver MCP, policy is resolved from the directory the server was **launched** in โ not from the `projectPath` a caller passes โ so an agent can't sidestep restrictions by pointing at a directory with no policy. Launch the MCP server from your project root (where `.q-ring.json` lives). Edits to `.q-ring.json` are picked up automatically (the policy cache invalidates on file change), so you don't need to restart the server.\n\nPolicy files are schema-validated and **fail closed**: an invalid `policy` object (say, a typo like `denytools`) raises a `PolicyConfigError` instead of being silently ignored, so a malformed rule can never widen access.\n\n```bash\n# View the active policy\nqring policy\n\n# JSON output\nqring policy --json\n```\n\nExample policy in `.q-ring.json`:\n\n```json\n{\n \"policy\": {\n \"mcp\": {\n \"denyTools\": [\"delete_secret\"],\n \"deniedKeys\": [\"PROD_DB_PASSWORD\"],\n \"deniedTags\": [\"production\"]\n },\n \"exec\": {\n \"denyCommands\": [\"curl\", \"wget\", \"ssh\"],\n \"maxRuntimeSeconds\": 30\n },\n \"secrets\": {\n \"requireApprovalForTags\": [\"production\"],\n \"maxTtlSeconds\": 86400\n }\n }\n}\n```\n\n### Exec Profiles\n\nRestrict command execution with named profiles that control allowed commands, network access, timeouts, and environment sanitization.\n\n```bash\n# Run with the \"restricted\" profile (blocks network tools and interpreters/shells; 30s timeout)\nqring exec --profile restricted -- npm test\n\n# Run with the \"ci\" profile (5min timeout, allows network)\nqring exec --profile ci -- npm run deploy\n\n# Default: unrestricted\nqring exec -- echo \"hello\"\n```\n\n**Built-in profiles:** `unrestricted`, `restricted` (denies network tools *and* interpreters/shells โ `python -c`, `node -e`, `bash` and friends can't exfiltrate injected secrets; 30s limit), `ci` (5min limit, blocks destructive commands).\n\n### Tamper-Evident Audit\n\nEvery audit event includes a SHA-256 hash of the previous event, creating a tamper-evident chain. Since v0.14 the chain is also anchored with a keyed HMAC stored in the OS keyring, so `qring audit:verify` detects truncation and whole-file rewrites โ not just in-place edits. Verify integrity and export logs in multiple formats. Events from MCP sessions are additionally stamped with the connecting client's self-reported identity (`clientInfo` name@version) โ shown in `qring audit` output and filterable with `qring audit --agent
![\"q-ring](\"https://raw.githubusercontent.com/I4cTime/q-ring/main/assets/social-card-optimized.jpg\")
\n![\"q-ring](\"https://glama.ai/mcp/servers/I4cTime/q-ring/badges/card.svg\")
\n\n\nStop 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.\n\n> ๐ **[View the Official Documentation](https://qring.i4c.studio/docs)** for a complete CLI reference, MCP prompt cookbooks, and architecture details.\n\n### Why q-ring?\n- **Superposition:** Store one key with multiple states (dev/staging/prod) that collapse based on context.\n- **Entanglement:** Link keys across projects so rotating one automatically updates them all.\n- **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.\n- **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.\n- **Seamless AI Integration:** 44 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.\n\n## ๐ Installation\n\nq-ring is designed to be installed globally so it's available anywhere in your terminal. Pick your favorite package manager:\n\n```bash\n# pnpm (recommended)\npnpm add -g @i4ctime/q-ring\n\n# npm\nnpm install -g @i4ctime/q-ring\n\n# yarn\nyarn global add @i4ctime/q-ring\n\n# Homebrew (macOS / Linux)\nbrew install i4ctime/tap/qring\n```\n\n### Docker (MCP server)\n\nThe repo ships a `Dockerfile` that builds the MCP server and exposes it through [`mcp-proxy`](https://github.com/punkpeye/mcp-proxy) โ useful for hosted MCP deployments (e.g. Glama) or keeping the server off the host entirely:\n\n```bash\ngit clone https://github.com/I4cTime/q-ring.git\ncd q-ring\ndocker build -t qring-mcp .\ndocker run --rm -p 8080:8080 qring-mcp\n```\n\n> 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.\n\n## โก Quick Start\n\n```bash\n# 1๏ธโฃ Store a secret (prompts securely if value is omitted)\nqring set OPENAI_API_KEY sk-...\n\n# 2๏ธโฃ Retrieve it anytime\nqring get OPENAI_API_KEY\n\n# 3๏ธโฃ List all keys (values are never shown)\nqring list\n\n# 4๏ธโฃ Generate a cryptographic secret and save it\nqring generate --format api-key --prefix \"sk-\" --save MY_KEY\n\n# 5๏ธโฃ Run a full health scan\nqring health\n\n# Something not working? Diagnose the install (keyring, audit, MCP wiring)\nqring doctor\n\n# Tab completion for your shell\nqring completion zsh > ~/.zsh/completions/_qring # also: bash, fish\n```\n\n## Quantum Features\n\n### Superposition โ One Key, Multiple Environments\n\nA single secret can hold different values for dev, staging, and prod simultaneously. The correct value resolves based on your current context.\n\n```bash\n# Set environment-specific values\nqring set API_KEY \"sk-dev-123\" --env dev\nqring set API_KEY \"sk-stg-456\" --env staging\nqring set API_KEY \"sk-prod-789\" --env prod\n\n# Value resolves based on context\nQRING_ENV=prod qring get API_KEY # โ sk-prod-789\nQRING_ENV=dev qring get API_KEY # โ sk-dev-123\n\n# Inspect the quantum state\nqring inspect API_KEY\n```\n\n### Wavefunction Collapse โ Smart Environment Detection\n\nq-ring auto-detects your environment without explicit flags. Resolution order:\n\n1. `--env` flag\n2. `QRING_ENV` environment variable\n3. `NODE_ENV` environment variable\n4. Git branch heuristics (`main`/`master` โ prod, `develop` โ dev)\n5. `.q-ring.json` project config\n6. Default environment from the secret\n\n```bash\n# See what environment q-ring detects\nqring env\n\n# Project config (.q-ring.json)\necho '{\"env\": \"staging\", \"branchMap\": {\"release/*\": \"staging\"}}' > .q-ring.json\n```\n\n### Quantum Decay โ Secrets with TTL\n\nSecrets can have a time-to-live. Expired secrets are blocked from reads. Stale secrets (75%+ lifetime) trigger warnings.\n\n```bash\n# Set a secret that expires in 1 hour\nqring set SESSION_TOKEN \"tok-...\" --ttl 3600\n\n# Set with explicit expiry\nqring set CERT_KEY \"...\" --expires \"2026-06-01T00:00:00Z\"\n\n# Health check shows decay status\nqring health\n```\n\n### Observer Effect โ Audit Everything\n\nEvery secret read, write, and delete is logged with a tamper-evident hash chain. Access patterns are tracked for anomaly detection.\n\n```bash\n# View audit log\nqring audit\nqring audit --key OPENAI_KEY --limit 50\n\n# Detect anomalies (burst access, unusual hours, chain tampering)\nqring audit --anomalies\n\n# Verify audit chain integrity\nqring audit:verify\n\n# Export audit log\nqring audit:export --format json --since 2026-03-01\nqring audit:export --format csv --output audit-report.csv\n```\n\n### Quantum Noise โ Secret Generation\n\nGenerate cryptographically strong secrets in common formats.\n\n```bash\nqring generate # API key (default)\nqring generate --format password -l 32 # Strong password\nqring generate --format uuid # UUID v4\nqring generate --format token # Base64url token\nqring generate --format hex -l 64 # 64-byte hex\nqring generate --format api-key --prefix \"sk-live-\" --save STRIPE_KEY\n```\n\n### Entanglement โ Linked Secrets\n\nLink secrets across projects. When you rotate one, all entangled copies update automatically.\n\n```bash\n# Entangle two secrets\nqring entangle API_KEY API_KEY_BACKUP\n\n# Now updating API_KEY also updates API_KEY_BACKUP\nqring set API_KEY \"new-value\"\n\n# Unlink entangled secrets\nqring disentangle API_KEY API_KEY_BACKUP\n```\n\n### Tunneling โ Ephemeral Secrets\n\nCreate secrets that exist only in memory. They never touch disk. Optional TTL and max-read self-destruction.\n\n```bash\n# Create an ephemeral secret (returns tunnel ID)\nqring tunnel create \"temporary-token-xyz\" --ttl 300 --max-reads 1\n\n# Read it (self-destructs after this read)\nqring tunnel read tun_abc123\n\n# List active tunnels\nqring tunnel list\n```\n\n### Teleportation โ Encrypted Sharing\n\nPack secrets into AES-256-GCM encrypted bundles for secure transfer between machines. Keys are derived with PBKDF2-HMAC-SHA512 (210 000 iterations) from your passphrase; each bundle records its iteration count, so bundles produced by older versions still unpack.\n\n```bash\n# Pack secrets (prompts for passphrase)\nqring teleport pack --keys \"API_KEY,DB_PASS\" > bundle.txt\n\n# On another machine: unpack (prompts for passphrase)\ncat bundle.txt | qring teleport unpack\n\n# Preview without importing\nqring teleport unpack