q-ring - Once, there was a file. (Official Trailer)

Guia

What q-ring is

q-ring is a command-line secrets manager and MCP server. It stores API keys and tokens in the credential store your operating system already ships (macOS Keychain, Linux Secret Service, Windows Credential Manager) instead of a plaintext .env file. It also gives AI coding agents in Cursor, Claude Code, Kiro, and VS Code a set of MCP tools to check for, inject, and, where your policy allows it, read those secrets.

The trailer is the story of the file. A .env was a reasonable home for a key when the only thing reading it was your own process. Once an agent can read your disk and run commands, that value travels: into a diff, into a conversation transcript, into a log line. q-ring takes the file out of the picture.

Who it is for

• Developers who run coding agents with shell access and want keys out of plaintext on their laptop.
• Anyone juggling dev, staging, and prod values under the same key names.
• Solo developers and small teams who still want a record of which process read which key, and when.

It is local by design: no account, no cloud service, no telemetry, and AGPL-3.0 licensed. The CLI and MCP server make no network calls of their own.

Try it

npm install -g @i4ctime/q-ring
# or: pnpm add -g @i4ctime/q-ring
# or: brew install i4ctime/tap/qring

qring doctor                 # checks the keychain, audit log, and MCP wiring
qring set OPENAI_API_KEY     # prompts for the value, nothing lands in shell history
qring list                   # names and status, never values
qring setup claude           # writes the MCP config (also: cursor, kiro)

What the trailer is pointing at

• "It locks your keys in the OS keychain." Each secret becomes one keychain item under a q-ring: service name, so you can see it in Keychain Access, Seahorse, or Credential Manager.
• "Hands them to your agents over MCP." The qring-mcp server ships in the same package. Its exec_with_secrets tool runs a command with a secret injected and returns redacted output, so the value never enters the transcript.
• "Never lets go." Key-level deny rules, approvals for sensitive reads, and a hash-chained audit log of every read, write, and delete.

The honest limit, stated in the project's threat model: q-ring does not stop a process running as you from reading a value, and once a permitted read hands a value to an agent that also has network access, no local tool can take it back. What it removes are the accidental paths.

Go deeper

• Getting Started
• Where to store API keys for Claude Code, Cursor and Codex
• Threat model on GitHub
• @i4ctime/q-ring on npm