lock family docs GitHub

Locks · lockmq

Installing lockmq

lockmq runs in Docker: one lockmq command, the launcher, runs every command in the signed release image. The full Docker guide is docker.md.

With Homebrew #

brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lox davidgodefroid/tap/lockmq

Homebrew asks you to trust a third-party tap once. lox is lockhub's CLI; the lockmq formula does not pull it in. brew install davidgodefroid/tap/lockfamily installs the whole family instead.

Then, in your project, lox add lockmq asks where your broker is, sets up its lock and starts its console. Keep lox run open in a terminal of its own, outside any agent: it serves the decisions.

cd your-project      # with lea: its projects directory
lox add lockmq       # asks about the broker, sets up the lock, starts the console
lox run              # in its own terminal: every ticket shows up here

Then start your agent in the project (claude, codex, gemini, …). lox add wires Claude Code (lockmq init claude); for Codex, Cursor or Gemini CLI, also run lockmq init codex (or cursor, gemini).

If a lea container already runs for the project, lox add says lea gets lock NAME at its next start: lea stop, then lea: lea mounts the locks' sockets when its container starts, so lea stop, then lea brings the new lock in.

By hand #

With lockmq's own installer:

# 1. Install the launcher (cosign checks the release and its image)
V=vX.Y.Z
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/lockmq/$V/scripts/install.sh"
less install.sh && LOCKMQ_VERSION=$V sh install.sh

# 2. In your project: the agent files, a broker profile, then a check of the setup
lockmq init claude          # or codex, cursor, gemini
lockmq profile add          # asks; or --non-interactive --url URL --user USER ...
lockmq doctor --fix --yes

# 3. Declare the lock, then start it with its hub and serve the decisions (lockhub's lox CLI)
lox add lockmq events
lox run             # a terminal of its own, outside the agent: starts the hub and the locks, then serves the decisions
lox attach events   # another terminal: the console's own questions: policy review, password (detach: Ctrl-P Ctrl-Q)

The console runs hub-attached only: lockhub starts it with its hub flags, and lockmq console on its own refuses to start. (lockhub's older lox up is deprecated: it prints "use lox run".)

lockmq init claude wires Claude Code to lockmq mcp, which the launcher runs in a throwaway container.

init, profile add and doctor are the same three verbs in every lock of the family, which lox add drives (profile add --non-interactive --json, init claude, doctor --fix --yes --json); no form of profile add takes or asks for a password.

Inside the containers localhost is the container itself: profile add offers host.docker.internal for a broker on your machine, and a broker container is reached by its name on a network shared with the console. Then ask your agent: "which queues have no consumer?", "why does orders.failed fill up?". Catalogue calls answer at once; stream reads pass on the default rules, and peeks wait for your decision in lox run (auto rules).

The launcher and its image #

brew install davidgodefroid/tap/lockmq or scripts/install.sh installs the lockmq launcher, which runs every command in ghcr.io/davidgodefroid/lockmq:X.Y.Z; the release's -vault image adds the pinned Vault CLI for credentials = "vault" (LOCKMQ_VAULT=1).

  • lockmq version prints the launcher's and the image's versions.
  • lockmq update updates both.

See docker.md, including your own build and migrating from a host install.

Linux and macOS, on amd64 and arm64; on Windows, run the launcher in WSL 2. The binaries are built with CGO_ENABLED=0.

Build #

CGO_ENABLED=0 go build ./cmd/lockmq
go test ./...
go test -tags integration ./test/integration/   # RabbitMQ 3.13 and 4.1 in Docker

Requires Go 1.26 or later.

Brand assets #

The logo, the demo and the social images are in site/assets. The demo is generated by scripts/brand: python3 scripts/brand/demo.py > site/assets/demo.svg, one frame of it rendered with render.mjs. The logo, the README banners in docs/assets, og.png and apple-touch-icon.png come from the Lock Family site kit.