q-ring
Keep API keys in your OS keychain and give coding agents only what policy allows
- Pricing
- Open source
- Platforms
- CLI, macOS, Linux
- Runs
- Locally
- Version
- 0.19.2
- Listing updated
- 3 days ago
About q-ring
q-ring is an open-source MCP server for security. It runs locally on your machine and is started by your AI client.
Secrets are stored in macOS Keychain, Linux Secret Service or Windows Credential Vault, and agents such as Cursor, Claude Code and Kiro ask through MCP tools instead of reading a .env file. Each key has a policy (allow, deny or approve), pending asks wait for your decision, and every ask lands in a hash-chained audit log that a verify command checks. A canary mode plants a fake key so any read raises an alarm.
The README names four unusual mechanics: superposition (one name with separate dev, staging and prod values chosen by flag, environment variable or git branch), entanglement (linked keys that rotate together), tunneling (in-memory secrets that expire by time or read count) and teleportation (AES-256-GCM encrypted bundles to share). The package ships 46 MCP tools and 68 CLI commands, and a file backend with a passphrase serves headless hosts like CI.
It is local only, licensed AGPL-3.0, and installed from npm or Homebrew. A Docker image exists but has no OS keychain inside it.
Install
Run in a terminal
claude mcp add q-ring --env QRING_FILE_PASSPHRASE='<QRING_FILE_PASSPHRASE>' -- npx -y @i4ctime/q-ringAdd to claude_desktop_config.json
{
"mcpServers": {
"q-ring": {
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"q-ring": {
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"q-ring": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"q-ring": {
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"q-ring": {
"command": "npx",
"args": [
"-y",
"@i4ctime/q-ring"
],
"env": {
"QRING_FILE_PASSPHRASE": "<QRING_FILE_PASSPHRASE>"
}
}
}
}Configuration
QRING_BACKENDSecret storage backend. Defaults to the OS keychain; set to "file" for headless hosts with no Secret Service (CI, containers).QRING_FILE_PASSPHRASEPassphrase for the encrypted file backend (AES-256-GCM). Required only when QRING_BACKEND=file — without it the file backend fails closed.QRING_FILE_BACKEND_PATHCustom path for the encrypted file store (default: ~/.config/q-ring/file-backend.enc).QRING_CONFIG_DIRDirectory for q-ring's registries — hooks, entanglement, approvals, canary webhooks, agent memory (default: ~/.config/q-ring).
What it does
- OS keychain storage
- Keys live in the native vault rather than plain-text files.
- Per-key policy
- Decide per key whether an agent is allowed, denied or must wait for approval.
- Tamper-evident audit
- Each event carries the hash of the previous one and can be verified.
- Canary keys
- A planted fake key flags any read as an alarm.
- Environment-aware values
- One key name can hold different values for each environment.
- Expiring secrets
- Ephemeral secrets self-destruct after a time or read count.
Good for
- Let Claude Code use an API key without pasting it into chat
- Review which agent asked for which secret
- Keep dev and prod values under one key name
- Inject secrets into a command with one run call
Pricing
Open source
Free and open source (AGPL-3.0)
Prices change. Check qring.i4c.studio before you buy.
q-ring FAQ
Does anything leave my machine?
The site says it is local only and nothing leaves your machine.
What does it cost?
It is free and open source under AGPL-3.0.
Does it work in CI or containers?
Set QRING_BACKEND=file with a passphrase for hosts without a keychain; the Docker image has no OS keychain.
Which agents are supported?
Cursor, Claude Code and Kiro are named.
Is q-ring free?
Yes. q-ring is open source, so you can use and self-host it for free.
How do I add q-ring to Claude Code?
Run this command in your terminal: claude mcp add q-ring --env QRING_FILE_PASSPHRASE='<QRING_FILE_PASSPHRASE>' -- npx -y @i4ctime/q-ring
What are the best alternatives to q-ring?
The closest alternatives to q-ring are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to q-ring

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools