q-ring 101 - agents on a leash (qring policy)

指南

What it does

The policy block in a project's .q-ring.json decides what agents can do through the q-ring MCP server: which tools they may call, which keys and tags they may read, and which commands exec may run. Keys marked --requires-approval go further. An agent's read waits until you grant a time-limited approval from your own terminal with qring approve. Approvals are HMAC-verified, carry a reason, are bound to the project, and expire on their own.

Try it

A policy in .q-ring.json at the project root:

{
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget", "ssh"],
      "maxRuntimeSeconds": 30
    },
    "secrets": {
      "requireApprovalForTags": ["production"]
    }
  }
}

Then from the terminal:

qring policy                                   # summary of the active rules
qring set STRIPE_KEY --requires-approval       # agents must ask for this one
qring approve STRIPE_KEY --for 900 --reason "agent wiring checkout tests"
qring approvals                                # live approvals, verified
qring approve STRIPE_KEY --revoke

Why it matters

An agent with MCP access to your secrets is useful exactly because it can act without you. That is also the risk: a prompt injection in a README or an issue can ask for a key, and the agent will try. Policy narrows what is possible before the agent asks, and approvals make the sensitive reads a deliberate human decision with a reason attached. When an agent is blocked on an approval-protected key, q-ring raises a desktop notification on Linux and macOS that names the key and the exact qring approve command.

Gotchas and good to know

• Over MCP, policy is read from the directory the server was launched in, not from a path the agent passes. Launch qring-mcp from your project root, where .q-ring.json lives. Edits are picked up without a restart.
• Policy fails closed. A typo such as denytools raises an error instead of being silently ignored, so a malformed rule cannot widen access.
• The approval gate covers bulk reads too: export_secrets and teleport_pack over MCP skip protected keys without a live approval.
• Once a permitted read returns a value to an agent that also has network access, nothing local can take it back. For production keys, deny them to agents and expose them only through exec_with_secrets, which injects the value and returns redacted output.

Go deeper

• MCP setup
• How the secret reaches an agent without landing in the transcript
• Threat model: the exfiltration question