Where are my secrets actually stored?

Your OS keyring (macOS Keychain, Windows Credential Manager, libsecret on Linux) via @napi-rs/keyring. q-ring never touches plaintext disk and never round-trips your secrets to a server.

Is there a SaaS or cloud component?

No. q-ring is 100% local. The optional dashboard runs on 127.0.0.1, the MCP server runs on stdio, and the CLI never makes outbound calls except when you explicitly run validate/rotate/JIT operations against your own providers.

Can multiple environments share one key name?

Yes - that's the whole point of Superposition. One key like API_KEY can carry distinct values for dev, staging, and prod. Wavefunction Collapse picks the right one based on flags, env vars, git branch, and your project manifest.

What happens when a secret expires?

Decay-aware reads will refuse expired secrets and warn on stale ones. Pair with the Agent for autonomous rotation, or run `qring rotate` to issue a provider-native rotation (with a quantum-noise fallback when the provider has no rotation API).

How do I migrate from .env files?

Run `qring import .env --skip-existing`. Comments, quoting, and escape sequences are preserved. Then delete the .env file and use `qring exec`, `qring env:generate`, or the MCP `get_secret` tool from your code.

Is this safe for AI agents to operate?

Yes. Every tool call is gated by your governance policy, sensitive secrets require HMAC approvals, and every read/write/delete is logged in a tamper-evident audit chain. Agents never see plaintext unless your policy allows it.

Is q-ring open source? Where's the code?

Yes - the full source is at github.com/I4cTime/q-ring under AGPL-3.0, and the package you install is published from that repo to npm as @i4ctime/q-ring. Every release is built by public CI, and the tool is listed in the official MCP registry, Smithery, PulseMCP, and Cursor Directory. q-ring is made by I4C Studio (i4c.studio).

What's the license? Is there a paid tier?

AGPL-3.0, free forever. There is no paid tier, no telemetry, and no upsell. If you want to support the work, the Ko-fi link in the footer is appreciated - but it never unlocks anything.

How stable is the CLI and MCP surface?

0.19 is the release candidate for 1.0. The CLI commands and flags, the MCP tool names and input schemas, the resource URIs, the .q-ring.json format, the keyring record format, the environment variables, the exit codes and both redaction tokens are frozen; from 1.0 they change only as semver allows, and anything removed is deprecated with a one-line stderr warning for at least one minor first (QRING_SILENCE_DEPRECATIONS=1 silences them). The full contract, including what stays experimental and the support window, is at github.com/I4cTime/q-ring/blob/main/docs/stability.md.

How is q-ring itself secured?

q-ring publishes a public threat model (github.com/I4cTime/q-ring/blob/main/docs/threat-model.md) covering trust boundaries, attackers considered, and known residual risks. v0.14 shipped a round of adversarial-audit hardening across the CLI, MCP server, and governance layer based on that model, and v0.19 a second internal pass: forty findings, each fixed with a regression test, written up with the surfaces found sound and the open items at github.com/I4cTime/q-ring/blob/main/docs/audits/2026-11-audit-pass-2.md. Found a real issue? Vulnerability disclosure runs through SECURITY.md - private reporting only, acknowledged within 48 hours with an initial assessment within 7 days.

v0.19.0 · Open source · AGPL-3.0

q-ringOpen-source OS keychain manager for AI coding agents

Name: q-ring
Author: I4C Studio

A free CLI and MCP server that keeps API keys in your operating system's keychain and hands them to Cursor, Claude Code, and Kiro on request. Nothing leaves your machine - no cloud, no account, no .env file.

Quick start Source on GitHub

Install

$ pnpm add -g @i4ctime/q-ring

Verified onSmithery Cursor Directory PulseMCP mcpservers.org

scroll

Open source, by the numbers

Everything ships in the box

across 10 groups

in 4 categories

full reference in docs

Cursor · Kiro · Claude Code · VS Code

Works everywhere

Drop into your AI editor of choice

MCP-native, hook-friendly, and CLI-first. q-ring slots into the agent toolchain you already use.

Drop-in plugin with hooks, secrets MCP, and one-shot env injection.

MCP server is detected automatically - zero-config setup.

Add q-ring as an MCP server in your project's .mcp.json.

Point .vscode/mcp.json at qring-mcp - or use the CLI directly.

The honest comparison

Why q-ring instead of `.env`?

Other tools were built for a human at a keyboard. q-ring is built so AI coding agents can read, rotate, and audit keys without a plaintext file ever existing - and you can read every line of how.

Capability	q-ring	.env files
Anchored to OS keyringmacOS Keychain, Linux Secret Service, Windows Credential Vault
MCP-native (AI agents)Cursor / Claude / Kiro can read & rotate secrets
Auto-expiring keys (decay)
Per-environment isolation
Free + open source	AGPL-3.0	-
Audit log of agent reads
Zero cloud dependency
One-shot env injectionqring run -- node app.js
Pre/post-commit hooks

Comparison reflects features at v0.19.0. PRs to update this table are welcome.

Try it in your browser

One palette, every command.

Press ⌘K anywhere on this site to fuzzy-search every page, MCP tool, and CLI command. Hit Enter to copy, navigate, or open docs.

46 MCP tools grouped by capability - pick one to copy its tool name into your editor.
33 CLI examples across 9 groups - from qring set to qring teleport pack.
Keyboard-first - arrow keys to navigate, Enter to act, Esc to close.

Browse all MCP tools

~/q-ring · live preview

What ships in q-ring

Quantum Features

35 capabilities inspired by quantum physics - engineered for real-world secret management. Click any feature to peek at how it works.

All

Quantum

Storage & Sync

Security & Audit

Execution & Agent

Quick Start

Five commands. Your secrets are quantum-secured. Step through them.

~ / terminal

# Store a secret (prompts securely if value is omitted)
$ qring set OPENAI_API_KEY sk-...[ok] saved OPENAI_API_KEY [global]

Model Context Protocol

MCP Integration

46 tools for seamless AI agent integration. Pick a category to browse the tools, then drop the snippet into your editor.

Tool	Description
`get_secret`	Retrieve with superposition collapse + observer logging
`promote_secret`	Copy one env state to another (no-op when equal; force to overwrite)
`diff_environments`	Per-key same / different / only-a / only-b / collapsed - statuses only
`list_secrets`	List keys with quantum metadata
`set_secret`	Store with optional TTL, env state, tags (re-setting keeps tags; clearTags removes them)
`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

Configuration

Drop in your MCP config

Same single binary, every host. Pick your editor and paste.

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

Under the hood

Architecture

A modular core engine bridging CLI and MCP to your OS-native keyring. Pick any module to see what it does, where it lives and a command that uses it.

qring CLI

MCP Server

Core Engine

@napi-rs/keyring

OS Keyring

src/core/(grouped by role)

crypto

envelope.ts

noise.ts

entanglement.ts

validate.ts

resolution

scope.ts

collapse.ts

import.ts

exec.ts

governance

policy.ts

approval.ts

hooks.ts

observability

observer.ts

scan.ts

linter.ts

context.ts

provisioning

provision.ts

tunnel.ts

teleport.ts

agent

agent.ts

memory.ts

dashboard.ts

Module inspector

Envelope

Storage format that wraps every secret with environment states, TTL, entanglement links and access counts

Source

src/core/envelope.ts

Try it

$ qring inspect OPENAI_API_KEY --project

Background daemon

Agent Mode

Autonomous background daemon that guards your secrets 24/7 - rotates, audits, and alerts so you don't have to.

60s

default interval, configurable

burst · off-hours · new source · tampered

256-bit

SHA-256 hash chain, tamper-evident

Scan Cadence. Scans every secret on the interval (set it with --interval <seconds>) and flags expiration, staleness, and anomalies locally.

Anomaly Heuristics. Reads the local audit chain for burst reads of one key, unusual-hour access, new sources, and tampering. Nothing leaves the machine.

Audit Chain. Every read, write, wrap, and push lands in a chained local log, so edits and deletions are detectable with qring audit:verify.

~/agent

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

Drop into your editor

Editor Plugins

Quantum secret management built into Cursor, Kiro, and Claude Code. Rules, skills, agents, commands, hooks, and the MCP connector - pre-wired to q-ring's 46 tools. Click any card for details.

~/install

# One command per editor:
$ qring setup cursor # or kiro / claude
# Claude Code can also install from the marketplace:
$ /plugin marketplace add I4cTime/q-ring

Operator surface

Status Dashboard

Headline KPIs, secrets table, manifest gaps, policy posture, approvals, hooks, anomalies, and a filterable 24h audit feed - streaming live from 127.0.0.1 with qring status.

127.0.0.1:9876/?token=•••

Health Summary

12of 14

12 healthy2 stale0 expired

Environment

prodauto-detected · git/main

Access (24h) +18%

Decay Timers

API_KEY

DB_PASS

STRIPE_KEY

Entanglement

API_KEY↔API_BACKUPDB_PASS↔DB_REPLICA

Anomalies

Live SSE updates

Snapshots stream every 5s. Search input, sort order, and scroll position survive each tick - no lost typing.

KPI strip + 14 panels

Headline KPIs, then health, env, manifest, policy, secrets table, decay, superposition, entanglement, tunnels, approvals, hooks, agent memory, anomalies, and a filterable audit feed.

Token-gated, local, never values

Self-contained Preact page on 127.0.0.1 - every route requires the per-launch ?token printed by qring status, other local users can't snoop, and secret values are never rendered, only metadata.

~/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

Common questions

Frequently asked

Everything you might want to know before adopting q-ring. If something isn't covered here, open an issue on GitHub - we update this list regularly.

Still curious? Open a question and we'll add it.

Free foreverEvery feature, command, and MCP tool. No paywall, no premium tier.
No telemetryq-ring never phones home. The only outbound call is the one you request.
Local-firstSecrets live in your OS keyring and the dashboard runs on 127.0.0.1.

Ready when you are

Stop leaking secrets.
Start shipping with confidence.

Three minutes to install, zero seconds of cloud setup. q-ring meets your AI agents where they already live - and your secrets never have to.

Quick start Read the docs Source on GitHub

Open source under AGPL-3.0. No accounts. No telemetry. No vendor lock-in. Read the code before you run it.