Frequently asked questions
Short answers, each drawn from the README and the docs. For anything not covered here, see the usage guide.
Which brokers does lockmq support?
RabbitMQ, through its management HTTP API (required), the stream protocol and AMQP 0-9-1 (both optional). It is tested against RabbitMQ 3.13 and 4.1. Other brokers are not supported. Protocols.
Which operating systems?
Linux and macOS, on amd64 and arm64. The separation relies on Unix accounts, socket peer credentials and terminals; native Windows is not supported. Install options.
How do I set it up?
Install it, run lockmq install once per machine to create the console account, then lockmq setup (a broker profile) and lockmq init (your agents) in the project, and start lockmq console in the console account’s own session. lockmq doctor checks the setup. Setup steps.
Which AI agents does it work with?
Claude Code, Codex, Gemini CLI and Cursor, wired by lockmq init. An agent talks to the console through the MCP server (lockmq mcp, over stdio) or through the lockmq CLI from a shell.
Does the agent ever see the broker password?
No. The agent never sees a credential and never opens a connection. Credentials are typed at console start (no echo), or read from the console account’s OS keychain or from HashiCorp Vault, and never appear in argv, environment, files, logs, the socket or error messages. URI passwords are stripped from every answer, including the URIs of shovels and federation links.
Can lockmq publish, purge or move messages?
No. v0.1 has no writes of any kind: no publish, purge, delete, move, requeue or shovel. The only operation that changes delivery state is the opt-in queue peek.
Why is reading a queue off by default?
Because RabbitMQ has no read-only way to look at a classic or quorum queue: the management get takes messages and requeues them, so they come back redelivered and a quorum queue’s delivery count grows. lockmq only peeks on a profile you set to tier peek, shows the side effects on the approval screen, never auto-approves a peek, and refuses one near the delivery limit. Streams have no such problem: a stream read moves nothing. More on peek.
Can the agent approve its own reads, or turn peek on?
No. Approval comes only from the console terminal: no socket method approves and no socket method loosens the policy. Switching a profile to tier peek is a loosening: written by anyone, it takes effect only after you confirm it in the console. Auto mode switches only from the console’s keyboard, is unavailable on production profiles and never applies to a peek.
Why does the console need its own OS account?
An agent in the console’s own account could read or type into its terminal. Separation is mandatory: without it the console refuses to start. lockmq install sets it up.
What happens if I don’t answer the approval prompt?
No answer within 5 minutes means denied. On a production profile you type the profile name to approve.
How is personal data in messages protected?
JSON bodies are masked per leaf: on production every string is redacted unless an allow rule names it; elsewhere mask rules, key-name heuristics and value detectors decide. Headers and properties follow rules and heuristics, and binary or compressed bodies are reduced to their size and hash. Masking is best effort: a value in a free-text field that nothing catches comes back in clear. More on masking.
Can I see the real values myself?
Yes, in the console only. Press Ctrl-O (or type :results) and the console prints each read and peek result in clear in its own terminal, while the agent still gets it masked. To let the agent itself receive clear values, type :unmask: a request with --unmask then shows PII: UNMASKED on its screen and is approved by you every time, never by auto mode. Both switches are console-only and audited.
What permissions should the broker user have?
Tag monitoring, empty configure and write, and read only where needed. RabbitMQ lets the read permission purge a queue, so grant it on the streams, and on queues only for profiles with tier peek. The console refuses an administrator or policymaker user on production. The broker user.
Can a message payload manipulate my agent?
It can try: lockmq treats the agent, and anything that can steer it such as message content, as not trusted. Every check runs in the console, every content read needs your approval, and results are framed as untrusted data.
What is logged?
One JSON line per login, policy change, catalogue call, refusal, decision, run and logout in the console account’s audit log (mode 0600), with the operation, target, message count, the agent’s intent and the client’s uid. Never a message body, header or property value.
Can the console run in Docker?
Not in v0.1: the console runs on the host, in the separated account. A broker in a container works like any other. lockmq and containers.
How does it relate to locksql?
Same model, different target. locksql gates databases, lockmq message queues and lockfile files; all three are built on lockkit, the shared framework for the console, separation, approval, masking, audit and MCP.
Is lockmq stable?
It is a pre-release (v0.1.x): any release may still change the config files, the MCP tools or the CLI.
Do I need Go to install it?
No. Releases ship static binaries and Linux packages. Building from source needs Go 1.26 or later.
How do I report a vulnerability?
Privately, through GitHub security advisories, not in a public issue. See SECURITY.md.