q-ring 101 - run without leaking (qring exec)

가이드

What it does

qring exec -- <command> starts your command with secrets placed in its environment, then filters the child's stdout and stderr. Any known secret value is replaced with [QRING:REDACTED] before it reaches your terminal, a CI log, or an agent's transcript. The process gets the real key. The output does not.

Try it

# Everything in scope, injected for one command
qring exec -- npm run deploy

# Only the keys this command needs
qring exec --keys OPENAI_API_KEY,STRIPE_KEY -- npm test

# Only keys tagged "backend"
qring exec --tags backend -- node server.js

# Locked-down profile: no network tools, no interpreters or shells, 30 s limit
qring exec --profile restricted -- npm test

Why it matters

Leaks rarely come from the store. They come from output: a debug line that prints request headers, a failing test that dumps its config, printenv in a build step. Once that output sits in a CI log or an agent transcript, it has been copied somewhere you do not control. exec closes that path, and it replaces the habit of exporting keys in your shell profile, where every process you start, your agent included, inherits them.

Agents get the same mechanism over MCP. The exec_with_secrets tool runs, say, a database migration with DATABASE_URL injected and returns the exit code plus scrubbed output, so the model sees the migration log and never the connection string.

Gotchas and good to know

• Redaction is a safety net, not a guarantee. It matches values longer than five characters, verbatim. If the program base64-encodes, URL-encodes, or splits a value, that output passes through untouched.
• Without --keys or --tags, exec injects every secret in scope. Narrow it, or use qring run, which injects only the keys declared in .q-ring.json plus qring:// references from your .env, and fails fast if one is missing.
• Expired secrets are skipped, and every injected read is written to the audit log.
• Profiles: unrestricted is the default. restricted refuses network tools such as curl and ssh, and interpreters and shells such as node, python, and bash, because any of them could forward the injected environment elsewhere. ci allows network access with a five-minute limit.

Go deeper

• Getting Started: inject instead of print
• How the secret reaches an agent without landing in the transcript
• Threat model: where plaintext can appear